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The buttons and handlers you’ve made in this section demonstrate sending a 
message in three different ways: 


= Asa system message: When you click the Receiver button using the 
mouse, mouseUp is sent as a system message. The Receiver button 
becomes highlighted when you click it because you selected the “Auto 
hilite” option. The notes play (or the screen flashes, if you used that 
option) as indicated in the button’s handler. 


m Asa Message-box message: When you use the send keyword in the 
Message box to send mouseUp to the Receiver button, the notes play 
as indicated in the button’s handler, but because the button was not 
actually clicked, it doesn’t become highlighted. 


= Froma handler: When you use the send keyword in the handler of the 
Sender button to send mouseUp, the Receiver button doesn’t become 
highlighted right away because the button isn’t actually clicked; but the 
notes play as indicated. Unlike the Message box, however, a handler can 
contain multiple commands to affect the Receiver button. In this case, 
you used the set command to change its highlighting and the wait 
command to create a delay. 


The point is that there are lots of ways for a handler to “get the message.” In 
the example you've just completed, the mouseUp_ handler in the Receiver 
button always responds to the mouseUp message, regardless of whether 
it comes from the system, the Message box, or another object's script. 


Action at a distance 


Where you place a handler in HyperCard affects its action. A handler at the 
“top” level, namely, in a button script or a field script, can respond only to a 
message received by that button or field. The same handler further “down” in 
the object hierarchy, at the card, background, or stack level, can respond to 
the message sent to any objects higher up, unless those objects intercept the 
message with their own handlers. (See Figure 3-1, earlier in this chapter.) 
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P R E F A C E 


About This Guide 


ELCOME TO THE HYPERTALK BEGINNER’S GUIDE. THIS GUIDE PROVIDES YOU 
with a starting point for exploring HyperTalk™, the language that’s built 
into HyperCard® software. With HyperTalk, you can write your own 
instructions, called scripts, for HyperCard to carry out. Writing scripts is 


called scripting. 


You can create, customize, and personalize HyperCard stacks without 
learning how to write scripts; but scripting with HyperTalk allows you even 


more control over what your computer can do for you. 


Preface: About This Guide 


If writing scripts sounds a lot like programming to you, you’re right—they 
are very similar; however, you do not need any previous experience with 
programming to be able to write scripts. If you can read this paragraph, then 
you can write a script. 


This guide introduces you to some basic scripting using a practice stack you 
create yourself. In this stack, you'll learn how to write scripts for traveling 
between cards, creating special effects, simulating animation, performing 
calculations, and more. Later on after you’ve completed this book, you can 
use your practice stack on your own as a place to try out new scripts. 


What you need to know to use this guide 


To get the most out of this guide, you should already know the basics of 
using your Macintosh® computer; for instance, how to use the mouse and 
the icons on the screen. You should also be familiar with how to get around 
in HyperCard. If you have gone through the first three or four chapters of 
the HyperCard User’s Guide, you probably know enough to begin. 
Specifically, you should know how to use buttons to get around in stacks 
and how to use the HyperCard menus and tools. You should have browsed 
through some stacks, looked through part of the Help system, and perhaps 
personalized a stack—for example, you might have used the Address stack to 
store some information. 


If you already have experience with programming in another language, you 
might want to go directly to the HyperCard Script Language Guide. 


This guide is intended to help you get started and let you get a feel for 
scripting on your own. You won’t find long, technical explanations of 
HyperTalk concepts here; but you will be able to see clearly how specific 
scripts work. 


How to use this guide 


Each chapter builds on what you’ve done in previous chapters, so it’s 
important that you start at Chapter 1 and work through the book 
sequentially. You should be able to go through an entire chapter in a single 
session at your computer, but you can take a break any time you like—or 
keep right on going, if it suits you. 


= In Chapter 1, “Getting Started,” you'll create a practice stack, which you'll 
use for scripting throughout this book. You'll make buttons for the 
stack and complete their scripts. 


= In Chapter 2, “Special Effects,” you'll learn about visual and sound effects 
in HyperTalk and add them to your stack. 


= In Chapter 3, “More About Messages,” you'll explore how buttons and 
other objects receive and send messages. 


a In Chapter 4, “Fields, ‘It,’ and Other Containers,” you'll get an introduction 
to how HyperCard stores information and performs calculations. 


= In Chapter 5, “Animation,” you'll learn two ways to create “moving 
pictures” with commands. 


= In Chapter 6, “Stacks You Can Build,” you'll look at two examples of 
useful stacks that you could create and script yourself, starting with 
materials available in the Idea Stacks that comes with HyperCard. 


m The Appendix, “HyperTalk Summary,” contains a list of all HyperTalk 
commands, functions, and other elements. 


You'll also find a glossary of terms, an index, and a Quick Reference Card 
containing all HyperTalk command and functions, which you can remove 
from this book and keep handy. 


At the end of the book is a Tell Apple card. By answering the questions 
and mailing the card to Apple, you help us improve our products and 
documentation. Fill the card out after you’ve worked with this guide. 
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Conventions used in this guide 


Several conventions are used in this guide to help make learning easier. The 
conventions are summarized here. 


When a new term is defined, you'll see the term in boldface. New terms and 
other, related terms and definitions are included in the Glossary. 


/\ Important Material set off like this is especially worth reading. Information in these 
boxes advises you of noteworthy circumstances or helps you avoid 
misfortune. / 


Sometimes definitions or cross- “* By the way: Paragraphs like this one contain additional information or 
references appear in the margin. interesting sidelights. 


A special font (Courier) is used to show HyperTalk words and statements; 
it’s also used to show any words or statements you should type. Courier 
font looks like this: 


set userLevel to 5 


Sometimes HyperTalk commands are shown in a generalized form, which is 
explained later in this book; for example, 


set property [of object] to value 


Words in italic are simply placeholders that would be replaced by some 
specific name or other value in an actual command. The square brackets [ ] 
are used to indicate optional parts; the brackets shouldn’t be included in an 
actual command. 
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For more information 


Because this guide is intended as an introduction for beginners, it is not 
comprehensive. HyperTalk comprises many commands, functions, 
keywords, and other elements that are not explained in this book. 


The HyperCard User’s Guide contains reference information for all menus and 
tools available. 


The HyperCard Help system provides on-line help while HyperCard is running. 
The Help system contains a HyperTalk reference section. 


The HyperCard Script Language Guide, published by Addison-Wesley 
Publishing Co. as part of the Apple Technical Library, is a complete reference 
to HyperTalk. It’s intended for those with some programming or scripting 
experience. 


The HyperCard Stack Design Guidelines, also published by Addison-Wesley, 
provides information on how to design and build professional-quality stacks. 
Its focus is the presentational aspect of stacks (for example, navigation 
methods and card layouts) rather than the mechanics of scripts. 


Other excellent books on HyperCard and on HyperTalk scripting can be found 
in almost any bookstore. 
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C H A F T E R ] 


Getting Started 


AVE YOU EVER WANTED TO CREATE YOUR OWN SOFTWARE—MAKE AN 
application program that does things the way you want, rather than 


someone else’s way? That’s what HyperCard® software allows you to do. 


This book takes you a step further into the power of HyperCard by 
introducing you to scripting—writing sets of instructions, called scripts, 
to customize HyperCard’s actions. Everything that happens in HyperCard is 
directed by a script. 


HyperCard scripts are written in the HyperTalk™ language, which is very 
much like the language people use in daily life. Believe it or not, you already 
know how to “say” things in HyperTalk—things that HyperCard would 
probably be able to understand and perform. 


Chapter 1: Getting Started 


You do not need any prior experience with computer languages to use this 
book. You should, however, be familiar with HyperCard and know how to 
get around in stacks. 


In this book, you'll practice scripting in a stack you'll build from scratch. 

Each chapter builds on material you’ve completed in previous chapters, so 
you should go through the chapters sequentially. In this chapter, you'll create 
the practice stack and write some simple scripts to control the actions 

of buttons. 


Start up HyperCard 


This book is meant to be used with HyperCard “up and running” on your 
Macintosh® system. You'll need to perform the steps as directed in the 
sections that follow to get the most out of the material. 


So, first start up HyperCard as you normally would. (The HyperCard 
User's Guide has instructions if you need them.) If you already have 
HyperCard running, go to the Home card. You're ready to go on when you 
see the Home card on your screen (Figure 1-1). 


= Figure 1-1 The Home card 


Set your user level 


To work with scripts, your user level must be set at Scripting. Change 
the user level on the User Preferences card of the Home stack by following 
these steps: 


1. Click the left arrow at the bottom of the Home card to go to the 
User Preferences card. 


2. Click the Scripting button. 


For now, the check box options Text Arrows and Blind Typing should be 
unchecked. You won't need the Power Keys option either, but if you 
prefer to use Power Keys with the Paint tools you may. Figure 1-2 shows 
the User Preferences card with Scripting selected. (Earlier versions of 
HyperCard may not have the Text Arrows option.) 


m Figure 1-2 The Scripting user level on the User Preferences card. 


When the user level is set at Authoring or Scripting, a new menu title, Objects, 
appears in the menu bar. Commands in this menu allow you to get 
information about and change properties of HyperCard objects—buttons, 
fields, cards, backgrounds, and stacks. (You'll learn more about objects later 
on.) The user level must be set at Scripting before you can look at, write, or 
change these objects’ scripts. 
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Create a practice stack 


Now that you've set the user level to Scripting, the next task is to create a 
stack where you can experiment with scripts. You can make a new stack at 
any time from anywhere in HyperCard; you don’t have to go back to the 
Home card. Just follow these steps: 


1. 


Choose New Stack from the File menu. 
A dialog box appears in which you can name the stack and specify its 
background. 


Click the check box to remove the check mark from “Copy current 
background.” 


You don’t want to copy the background for this practice stack, so 
“uncheck” the box. The new background will be completely blank. 


. Type a name for the stack—for example, Practice Stack 


In this book, your practice stack is referred to simply as that—but you 
can name your stack anything you like; “Practice Stack,” “Test Stack,” 
“Pilgrim’s Progress,” or whatever. If you make an error while typing the 
name, use the Backspace (Delete) key to erase it and retype. The dialog 
box should look similar to the one in Figure 1-3. 


Figure 1-3. The New Stack dialog box 


4, When you're ready, click New (or press Return). 


You should see a completely blank card on your screen with only the 
menu bar showing along the top. This card is the first—and right now, 
the only—card of your practice scripting stack. 


When you create a new stack, you automatically get three things: the stack 
itself, a background, and the first card. If you were to select the “Copy 
current background” option, you would also get the background pictures, 
fields, or buttons of the card you were on when you chose the New Stack 
command. Otherwise, as in this case, you have a blank card to work with. 


Set up the background 


You can think of the background in HyperCard as a kind of “holding area” for 
general elements. If a button, a field, or a picture is in the background, then it 
appears on every card that shares that background. Putting a button in the 
background, for example, allows you to have that button constantly available 
throughout a number of cards—you don’t need to re-create it on every card. 
So far, the practice stack has only one background, so all cards you create will 
share that background. 


In this section you'll first create a title that will appear on all cards of the 
stack. Then you'll put a Home button and some buttons for traveling into 
the background, and you'll write scripts for the buttons. 


Set up the background , 


Before you go on, 


= Press Command-B to work in the background. 
(You could also choose Background from the Edit menu.) 


The menu bar appears with striped lines top and bottom, indicating that 
you're working in the background (Figure 1-4). 


m Figure 1-4 Working in the background 


Striped lines indicating 
background 


** Keyboard shortcuts: The steps you follow throughout this book make 
use of a number of shortcuts for menu commands and for getting 
around in HyperCard. Some of these shortcuts may be new to you at 
first. You'll have plenty of opportunity to practice them. 


It’s a good idea to include a visible title or other identifier on each card of a 
stack, so you can always tell which stack you’re in. Put a title on your practice 
stack using the steps that follow. 


Putting a title on the stack 


“« Are you in the background? You should see stripes in the menu bar to 
indicate you’re working in the background. If you don’t see stripes, press 
Command-B. 
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1. Choose the Paint Text tool from the Tools menu. 


If you prefer to work with a palette, you can turn the Tools menu into a 
palette by dragging past its bottom edge to “tear” it off the menu bar. 


2. Press Command-T to select the text style. 


(You could also choose Text Style from the Edit menu or double-click the 


Paint Text tool on the Tools palette.) 
The Paint Text tool 
The Text Style dialog box appears (see Figure 1-5 for an example). 


m Figure 1-5 The Text Style dialog box 


3. Choose a font you like in a large, readable size—for instance, 
New York 18. 


4, Click the “Center” button in the lower-left corner of the box so 
that your text will be centered as you type it. 


5. Click OK. 
You're ready to put the title on the stack. 
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6. Click in the center of the card near the top to set the insertion 
point and then type the name of your stack. 


Use the name you gave the stack when you created it. If you make a 
typing error, use the Backspace (Delete) key to delete and retype before 
clicking anywhere else. You can also just erase the name with the Eraser 
and start over. 


When you’re finished, the screen should look something like Figure 1-6. All 
you've added so far is the title. 


m Figure 1-6 The practice stack with a title 


The name you typed into the New Stack dialog box when you created the 
stack is the name HyperCard uses to identify the stack. The title you added 
to the background is for convenience, so that you or other people can readily 
tell which stack it is. 


Home, sweet Home 


The Button tool 


Whenever you see a small picture of a house in HyperCard, you can be pretty 

sure that clicking it will take you to the Home card. In the following 

sections, you'll add a Home button to your stack and complete its script. 

“> By the way: In the HyperCard User's Guide you learned how to copy and 
paste buttons with prewritten scripts, such as Home buttons. In this 
book, you'll complete the scripts yourself. 


Making a button 


You can always get a new button by choosing New Button from the Objects 
menu. In this book, you'll use a keyboard shortcut to make buttons. Follow 
these steps: 


1. Make sure you’re working in the background. 
You should see striped lines in the menu bar. If you don’t see stripes, 
press Command-B. 

2. Choose the Button tool from the Tools menu. 
The pointing hand (Browse tool) on the screen changes to an arrow 


pointer. 


3. With the pointer anywhere on the card, hold down the Command 
key. 
Notice that the arrow pointer changes to a crosshair. 


4, While holding down the Command key, press the mouse button 
and drag to create a small square button about half an inch square. 


Release the mouse button and the Command key when the button is 
about half an inch square. The new button is automatically selected—you 
can tell by the moving dotted lines around its edges. (This effect is 
sometimes referred to as “marching ants.”) While it’s selected you can 
change its size by dragging a corner or move it by dragging its center. 


5. Move the button to the lower-left corner of the card by dragging 
its center. 


Because the button is in the background, it will appear in this position on 
every card in the stack, so you can always go Home. 
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Customizing the button 


HyperCard buttons have a variety of styles and features from which to 
choose. You customize a button’s appearance and actions through the 
Button Info dialog box. 


1. Double-click the button to see the Button Info dialog box. 
(You could also choose Button Info from the Objects menu.) 


Figure 1-7 shows this box. 


= Figure 1-7 The Button Info dialog box 


Notice that the insertion point is blinking in the Button Name box, ready for 
you to type a name. 
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Some house icons 


2. Type Home (but don’t press Return). 
If you press Return prematurely, don’t worry; just double-click the 
button again to get back to the Info dialog box. 

3. Click the “Auto hilite’ check box to select it. 


The “Auto hilite” option causes the button to become highlighted when 
it’s clicked, which gives you a visual signal that you’ve clicked it. 


Leave the “Show name” option unchecked; you'll put an icon on this 
button instead. 

4. Click the Icon button. 
Another dialog box appears in which you can select an icon for the 
button. 

5. Choose one of the house icons. 
Scroll through the window until you find the house icons and click the 
one you want. 

6. Click OK. 


All the dialog boxes disappear. Your new button now has the house icon 
on it. 


Next, you'll write a script for this button. 


Set up the background 
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Scripts are created and changed in a special box called the script editor. To 
see the script for the new Home button: 


1. Double-click the Home button. 


You see the Button Info dialog box again. 


2. Click the Script button. 


You see a large dialog box with two lines of text already in the window. 
This box is the script editor for the Home button. (See Figure 1-8.) 


= Figure 1-8 The script editor 


————ldeentification line 


L- ——————— a ses tl appear 
automatically 
in button scripts 


Notice that the top line identifies this script as “Script of bkgnd button 

id 1 = ‘Home’ "—your new button. Notice also that two lines of text appear 
in the box already—on mouseUp and end mouseUp—with the 
insertion point blinking in between. All scripts for new buttons have the first 
line and last line filled in for you. 


The next step is to type the statement that defines the action of the button. 


3. Type go Home 


The new line should appear between the existing lines. If you make a 
mistake, use the Backspace (Delete) key to erase and type over. 


The three lines constitute the completed script for the Home button: 


on mouseUp 
go Home 
end mouseUp 


As you might guess, these instructions describe what should happen when 
someone clicks the Home button. You have one more step before you're 
finished, but first, here’s a brief description of how the script works: 


Whenever you move the mouse, the Macintosh computer and HyperCard 
software track the movement electronically. You see the movement as a 
change in the position of the pointer on the screen. When you press and 
release the mouse button, electrical signals are sent, something like when you 
turn a switch on and off. The same thing is true when you press different 
keys on the keyboard. The HyperCard software interprets these signals from 
the system and translates them into HyperTalk system messages. 


MouseUp isa system message that means the mouse button has been 
released; an on-screen HyperCard button receives this message when 
someone clicks it (that is, positions the Browse tool on it and then presses 
and releases the mouse button). 


Whether something happens when the on-screen button receives the 
mouseUp message depends on whether the button’s script contains any 
instructions for that message. 


The first line, on mouseUp, signals HyperCard that further instructions 
exist. The lines that follow on mouseUp are HyperTalk statements that 
make up the instructions. The last line, end mouseUp, indicates the end 
of the instructions. 


The word go is a HyperTalk command; it means what you might expect. 
Go must be followed by a destination—a description of a card or a stack. In 
this case, you used the name of the stack, Home. You could also have 
typed a more elaborate description that would mean the same thing, such as 


go to card 1 of stack "Home" 
Translated into English, the instructions say 


“When this button is clicked, go to the first card of the Home stack. 
That’s all.” 
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The Browse tool 
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To leave the script editor, 


4, Click OK. 


The script editor disappears, and you're back to the practice stack. (If you 
click Cancel the same thing will happen, but your instructions won't be in 
the script.) 


Trying it out 
Now see if the Home button works as it’s supposed to. 
1. Choose the Browse tool from the Tools menu or palette. 


2. Click the Home button. 


The next thing you see on the screen should be the Home card. Welcome 
Home! 


If something else happened, such as a dialog box saying “Can’t understand,” 
then you might have made a typing mistake. Switch to the Button tool and 
double-click the Home button to check the script. Make sure everything is 
correct, and then click OK and repeat the steps. 


To get back to the practice stack: 


1. Press Command-M to see the Message box. 
(You could also choose Message from the Go menu.) 
The insertion point should be blinking inside the Message box, ready for 
you to type. 


If for any reason you previously typed something into the box, the 
earlier entry would still be there. Just start typing and the old text will 
be replaced. 


2. Type go to stack "Practice Stack" (use the actual 
name of your stack in quotation marks). 


Buttons for traveling 


. Press Return. 


You should now see your practice stack on the screen. 


If something else happened, such as a dialog box asking you where the 
stack is, then check your stack name for correct spelling and 
completeness. For instance, if Stack is part of your stack’s name, you'll 
have to include that word in the Message box. 


. Close the Message box (click its close box or press Command-M 


again). 


As you see, you can use the go command both in scripts and in the 
Message box. Most HyperTalk commands work in both places; you can 
communicate directly with HyperCard through the Message box. 


Next you'll create two “travel buttons” to allow you to go back and forth 
between cards in the stack. (Right now there’s still only one card, but you'll 
add more shortly.) 


Making two new buttons 


Use the same steps as you did for the Home button: 


1. 


Make sure you are working in the background. 


You should see stripes in the menu bar. If you don’t see stripes, press 
Command-B. 


. Switch to the Button tool and use Command-drag to create two 


new transparent buttons. 


Make them about the same size as the Home button. 


. Position these two buttons side-by-side at the bottom of the card, 


roughly in the center. 


Drag each button by its center to move it. 
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Customizing the button on the right 


Make the button on the right into a “move forward” button: 


1. 


With the Button tool still selected, double-click the button on 
the right. 


The Button Info dialog box appears. 


. Name the button Next 
. Click the check box to select “Auto hilite.” 
. Click the Icon button to see the available icons. 


. Choose an icon that points to the right. 


You can choose any size arrow or pointing finger. Click the one you want. 


. Click OK. 


The boxes disappear. You should see the arrow or finger on the button. 


Customizing the button on the left 


Repeat the steps for the remaining button: 


1. 


With the Button tool still selected, double-click the button on 
the left. 


The Info dialog box appears. 


. Name the button Previous 
. Click the check box to select “Auto hilite.” 


. Click the Icon button to see the available icons. 


5. Choose an icon that points to the left. 


It’s best to use the same icon as you chose for the first button, but 
pointing the opposite way. 


6. Click OK. 


The two buttons should now have matching icons pointing away from 
each other. 


Completing the scripts 


You want the button on the right to take you to the next card in the stack 
and the button on the left to take you to the previous card. Put your 
instructions into the buttons’ scripts: 


1. Hold down the Shift key and double-click the right-arrow button 
to see the script editor. 


(You could also double-click the button and then click Script in the 
Button Info box. ) 


2. Type go to next card between the existing lines. 


3. Click OK. 


The script editor disappears. Repeat the steps for the remaining button. 


4, Hold down the Shift key and double-click the left-arrow button to 
see the script editor. 


5. Type go to previous card _ between the existing lines. 


6. Click OK. 
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You have now completed both buttons’ scripts. The script for the button on 
the right contains 


on mouseUp 
go to next card 
end mouseUp 


For the button on the left, it’s 


on mouseUp 
go to previous card 
end mouseUp 


These buttons can now be used to travel back and forth in the practice stack, 
card by card. Moving to adjacent cards isn’t the only possiblity, of course; you 
can create other buttons to take you to any card of any stack you want by 
specifying in a script where you want to go. 


So far in this stack, there’s nowhere else to go. It’s time to add some cards. 


Fill out the stack 


Before you add new cards, it’s a good idea to label this card in some way so 
that you'll know when you're at the first card. Later in this chapter you'll 
learn a way to label other cards you add as well. 


First, create a text field in the background to hold the label. Follow these 
steps: 


1. Make sure you're still working in the background. 


If you don’t see stripes in the menu bar, press Command-B. 


Typing a label 


The Field tool 


. Choose the Field tool. 


. Hold down the Command key and drag to create a new field about 


an inch and a half wide and roughly a quarter to half an inch high. 


. Move the field to the card’s upper-right corner, beside the title. 


Drag it by its center, just as you did with the buttons. 


5. Double-click the field to see its Info box. 


. Click “Rectangle” to set the field’s style. 


. Click the Font button. 


The Text Style dialog box appears. 


Select a font and size. 


Geneva 12, which may be already selected, is a good choice. 


. Click OK (or press Return). 


The Text Style dialog box closes, and you’re back to the card. 


The field you created will appear on every card because you put it in the 
background. Text in the field, however, can be different on every card. Type a 
label for this card into the field: 


1. 


Choose the Browse tool. 


Notice that when you choose the Browse tool, the stripes disappear 
from the menu bar. You are no longer in the background of the stack. 


. Click inside the field to set the insertion point, and then type 


the words This is Card 1 


The text you just typed will appear only on this card; the field, however, will 
appear on all cards, and can contain different text in each card. 
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At last, you’re ready to add some cards to this slim stack. 


1. Press Command-N five times. 
(You could also choose New Card from the Edit menu five times.) 


Although you haven’t seen much happen on the screen, you've just increased 
the size of your stack from one card to six cards. Notice that the field in the 
upper-right corner is blank, indicating that you are no longer looking at the 
first card. You are on the last card you inserted, or the sixth card of the stack. 


2. Click the right-arrow button, and you should find yourself on 
Card 1 again. 


Cards in stacks are arranged in a circle, so the first card is the next one 
after the last card. 


A script to label all cards 


You could label all cards in your stack by going to each one and typing its 
number into the field, just as you did for Card 1. But you can also write a 
script telling HyperCard to do it for you. Here’s how: 
1. Choose Stack Info from the Objects menu. 

The Info dialog box for the stack appears. 


2. Click the Script button. 


The script editor for the stack appears. You can tell it’s the stack script by 
the identifying line at the top. 


3. Type the lines that follow exactly as written. Press Return at the 
end of each line: 


on openCard 
put "This is Card" && number of this card into field 1 
end openCard 


Be sure that you type two ampersands (&&) and that you include the 
quotation marks. 


When you press Return after the final statement, you'll notice that the 
last line moves over to the left, but the middle line remains indented. This 
automatic indenting helps you check your scripts. On and end 
should always line up at the leftmost edge of the script editor box after 
you press Return the final time; if they don’t, you might have left out 
something important and should check the script again. Pressing the Tab 
key also checks the formatting. 


If everything looks correct, 


4, Click OK. 
The script editor disappears. 


When you created the new cards, HyperCard numbered the new cards in 
sequence automatically. This script labels each card as you go to it by putting 
“This is Card” and the card’s number into the field. Try it out: 


5. Click the right-arrow button to go to each card. 


You should see the phrase appear in the field automatically as you go, 
with the correct card number. 


Just as the message mouseUp goes to a button when it’s clicked, the 
message openCard is sent to the current card whenever you go to it. The 
put command does what you would expect—it puts something where you 
want it to go. 


The double ampersand (« &) connects two pieces, or strings, of text 
together with a space in between. One piece of text is “This is Card” and the 
other piece is the card’s number, which you specified as number of 
this card. If you wanted to join two strings of text together without 
a space, you would use a single ampersand. 
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In English, the script says: 


“When a card opens, put the phrase “This is Card” and the card’s number, with 
a space in between, into field 1. That's all.” 


All cards in the stack will be labeled by this script because it’s a stack script. A 
stack script can have an effect on all backgrounds, cards, fields, and buttons 
belonging to that stack. You could have put the script at the card level, but 
you would have had to copy it to every card’s script or it wouldn’t work for 
every card. 


The advantage of using a script to label cards is that you won't have to 
worry about labeling the cards yourself, even if you add or delete cards. 
HyperCard will take care of it for you. 


Add a button to the Home card 


Wouldn’t it be convenient to have a button on the Home card that would 
take you directly to your practice stack? Create one now: 


1. Click the Home button to go to the Home card. 


2. Choose the Button tool and create a new button. 


Use Command-drag to create the button; make it fairly wide. Move it to 
any open space you have on the Home card. 


2, 
h 


By the way: If you need room, you can move many of the Home card 
buttons just by clicking them with the Button tool and dragging them 
to a new location. (Some buttons are transparent; you have to move 
their underlying graphics separately.) 


3. Double-click the button to see its Info box. 


You could also choose Button Info from the Objects menu. 
4, Name the button My Stack 
5. Click “Show name” and “Auto hilite” to select them. 


6. Click “round rect” to make the button style a rounded rectangle. 


‘\ Important 


7. Click the Script button to see the script editor. 


8. Type the command that will take you to your practice stack. 
Can you do it? Give it a try. Here’s a hint: you typed this command into 
the Message box earlier after testing your Home button. 

9. Click OK. 


You should see the Home card with the new button. If the button is 
too small and you can’t see all of the words, drag one of the button’s 
corners to make it larger. 


10. Choose the Browse tool and click the My Stack button. 


If you went to Card 1 of your practice stack, congratulations! 


If something else happened, then you might have misspelled a word or left 
out a space. If you got a directory dialog box asking where the stack is, you 
might have typed the name incorrectly. 


Any of these statements would work in the button’s script: 
go to stack "Name" 

go to "Name" 

go "Name" 

go Name 


The placeholder word Name stands for whatever you named your stack 
when you created it. Be sure that you type the name exactly as it appears in 
the stack’s Stack Info box. 


Although it’s possible in many cases to omit the quotation marks and still 
have a working statement, as a general rule it’s best to include the marks. 
Without them, HyperCard is sometimes able to carry out the command the 
way you intend, but not always. Quotation marks remove any ambiguity. A 


You should now be at Card 1 of your practice stack, ready to go on. Or, if 
you'd like to take a break, go ahead. In the next chapter you'll write some 
more elaborate scripts. 
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What you’ve done so far 


In this chapter you've created a stack in which you can practice scripting in 
the rest of this book and on your own. You’ve completed scripts for three 
background buttons using the HyperCard script editor. Finally, you’ve created 
a background field and written a script to label all cards by number in that 
field. 


Here’s a list of the HyperTalk words you have learned: 


Commands 

go This command is used to move from one card to 
another, within a stack or between stacks. The 
word go must be followed by the name of a card 
ora stack. Go works in scripts or in the Message 
box. 

put As you might guess, this command takes 
something and puts it somewhere. The word put 
must be followed by the name of the thing you 
want to put somewhere and the name of the place 
you want to put it. 

Messages 

mouseUp A system message. When you click something, such 
as a button on the screen, the system sends 
mouseUp when the mouse button is released. (If 
the pointer is moved off the screen button before 
the mouse button is released, mouseUp is not 
sent.) 

openCard A system message sent to a card when it is opened. 

Modifiers 

next This word means the same thing as the English 
word. 

previous Another word that means the same thing as the 


English word; it can be abbreviated prev. 


Miscellaneous 


& 


& & 


end 


on 


to 


(Ampersand) This symbol joins two pieces, or 
strings, of text together. 


(Double ampersand) This combination symbol joins 
two pieces of text with a space in between. 


This word signals the end of a set of instructions. It 
must be followed by the name of a message, such as 
mouseUp. All HyperTalk scripts conclude with an 
end_ statement. 


This word signals the beginning of a set of 
instructions. It must be followed by the name of a 
message, such as mouseUp. 


The word to _ is used different ways in HyperTalk. 
It’s optional with the go command; go to 
stack "Scripting" meansthesameas go 
stack "Scripting". 
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Special Effects 


OU MIGHT ALREADY KNOW THAT BUTTONS, FIELDS, CARDS, BACKGROUNDS, 
and stacks in HyperCard are called objects. More specifically, objects are 


HyperCard elements that can 
m receive and send messages 


m act On messages according to instructions in their scripts 
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Not all elements in HyperCard are objects. Elements that are not objects 
include any graphics or text you create with the Paint tools, the text inside 
fields, any dialog boxes that appear, the menu bar at the top of the screen, 
and the menus and palettes. The Message box is also not an object, even 
though you can send messages with it. 


When you copy (or cut) and paste any object, its script goes along with it; 
thus, you don’t have to build a button from scratch, as you did with the 
buttons in Chapter 1, every time you want one. 


In this chapter you’ll create more buttons and add some special effects to 
button scripts using new commands. 


If you took a break and quit HyperCard at the end of Chapter 1, you need to 
start up HyperCard again. Use the button you added to the Home card to get 
to your practice stack. You're ready to go on when you see Card 1 of your 
practice stack on the screen. 


Some visual effects 


HyperCard’s visual effects make movement between cards and stacks 
noticeable and visually interesting. 


You add visual effects to scripts using the visual command. In the 
sections that follow, you'll add visual effects to your stack’s buttons. 


Right now, the practice stack is pretty bare visually, so visual effects won't 
be very effective. Let’s add some graphics to the stack. 


/\ Important  HyperCard visual effects aren’t visible with color or with multiple grays 
selected. If you have been using color, go to the Control Panel (available in 
the Apple menu) and change the Monitors setting to “Black & White/Grays” 
and the number of grays to 2. A 
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Adding graphics 


The Rounded 
Rectangle tool 


The Line Size box 


Using the Paint tools, you'll put a border on all cards to help you see some of 
the visual effects: 


1. 


Press Command-B to work in the background. 

The menu bar becomes striped. 

Putting the border in the background means you'll have to draw it 
only once. 

Choose the Rounded Rectangle tool from the Tools menu. 


The Browse tool changes to the crossbar pointer. 


. Choose Line Size from the Options menu to see the Line Size 


dialog box. 


Click the line size you want. Choose one of the wider sizes. 


The Line Size box closes automatically when you select a size. 


. If you want to make a patterned border, choose a pattern from 


the Patterns menu. 


If you don’t choose a pattern, the border will be a black line. 


. Hold down the Option key, position the crossbar inside the 


upper-left corner of the card, and drag to the lower-right corner. 
Then release the mouse button. 


Using Option-drag draws the rectangle with the selected pattern. If you 
didn’t choose a pattern, you don’t need to use the Option key. 


If you don’t like the position of the rectangular border and want 
to try again, press Command-Z to undo the drawing before clicking 
anywhere else. 
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7. Press Command-B or choose the Browse tool to stop working in 
the background. 


You can add some of your own graphics at the card level if you like; however, 
leave cards 4, 5, and 6 blank. You'll need to draw on them later in this book. 
Figure 2-1 shows a sample Card 1 with the background border completed and 
some optional, whimsical graphics added to the card. (The graphics were 
copied and pasted from the Art Ideas stack.) 


m Figure 2-1 Sample Card 1 with graphics 


The card border you added to the practice stack is only for the purpose of 
being able to see certain visual effects; cards do not necessarily have to have 
borders. If you were creating a stack for some other purpose, you would 
want to consider the card layout and inclusion of graphics carefully. For 
information on designing stacks, see the HyperCard Stack Design Guidelines. 
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The Visual command 


Visual effects are most commonly used during transition between cards. In 
this section you'll add effects to the arrow buttons and to the buttons that 
take you back and forth from your stack to Home. 


Adding effects to the arrow buttons 


From any card in your practice stack, follow these steps to add a visual effect 
to the right-arrow button: 


1. Choose the Browse tool and then hold down the Command and 
Option keys. 


Pressing these two keys lets you see the outline of all buttons on the 
card—even invisible (transparent) ones. 


2. Still holding down Command and Option, click the right-arrow 
button. 


The script editor appears showing the button’s script. (Release the keys 
after you click.) 


The Command-Option-click shortcut allows you to go directly to a 
button’s script without switching to the Button tool first—a handy 
feature when you’re doing a lot of scripting. 


(In versions of HyperCard earlier than 1.2, this shortcut doesn’t work. 
An alternative is to switch to the Button tool and Shift-double-click 
the button.) 


>, 
“ 


By the way: Even though you had to switch to the background when you 
created this button, you do not have to switch to the background to 
change its script. 


3. Click before the word go to place the insertion point at the 
beginning of the second line. 
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4, Type visual effect scroll left and press Return. 
The script should now look like this: 


on mouseUp 
visual effect scroll left 
go to next card 

end mouseUp 


5. Click OK. 


The script editor disappears. The Browse tool should still be selected if 
you used the Command-Option-click shortcut. 


To see how the visual effect works, watch the screen and click the button 
with the Browse tool. You should see the next card appear to slide in from 
the right. 


6. Add the same effect, but going the opposite direction, to the left- 
arrow button. 


Follow the same steps as you did for the right-arrow button, but type 
visual effect scroll right 


The scroll effect causes the entire screen image, including the 
background elements, to move in the direction indicated. It’s good for giving 
a page-turning effect. 


By the way: Notice that you use scroll left for the right arrow 
and scroll right for the /eft arrow to simulate page turning. 


Adding an effect to the Home button 
This time you'll use a different effect: 


1. Press Command-Option and click the Home button. 
(You could also use Shift-double-click with the Button tool selected.) 
The script editor for the Home button appears. 

2. Place the insertion point at the beginning of the second line, 
before the go statement. 

3. Type this line and press Return: 
visual effect wipe left slowly 
Remember to press Return so that the statement is on its own line, but 
don’t click OK to close the script editor yet. 

4, Leave the script editor on the screen for now. 


The word slowly isa modifier that controls speed. You can choose from 
four options: 


very fast 

fast 

Sslow[ly] 

very slow[ly] 

(The -/y is optional with slow.) 


If you don’t choose any of these, the effect runs at “normal” speed. The 
speed modifier should always follow the name of the effect. 
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Adding the same effect to the My Stack button 
on the Home card 


Rather than type the command over again, you can just copy the command 
from the script editor of the Home button, which should still be on your 
screen. 


(If you closed the script editor, press Command-Option and click the Home 
button to open it again.) 


1. 


Drag across the line with the visual effect as you would any text 
line to select it. 


Make sure you select only the line with the visual effect. 


. Press Command-C to copy the line. 


The command statement is copied to the Clipboard. 


. Click OK to save the script and close the script editor. 


. Click the Home button with the Browse tool. 


The Home card appears. Notice the visual effect during transition—the 
wipe effect you just added. It’s as though the first card is “wiped off” 
the next one. 


. Command-Option-click the My Stack button to see the button’s 


script editor. 


. Place the insertion point at the beginning of the second line, 


before the go statement. 


. Press Command-V to paste the visual effect. 


You might also have to press Return to put the go command ona 
separate line after you paste. 


. Click OK to save the script and close the script editor. 


9, Click the My Stack button with the Browse tool. 


You should go back to Card 1 of the practice stack, seeing the wipe effect 


again. 


Being able to cut and paste scripts can save you a lot of typing. You must use 


the keyboard shortcuts for Edit menu commands when you're using the 


script editor, however; the Edit menu is not available. Table 2-1 lists the script 
editor keyboard commands, 


m Table 2-1 Script editor command summary 


Key press 


Command-A 
Command-C 
Command-F 
Command-G 
Command-H 


Command-P 


Command-period 


Command-V 
Command-X 


Enter 


Option-Return 


Retum 


Tab 


Action 


Select entire script 

Copy selection to Clipboard 

Find text (same as Find button) 
Find next occurrence of same text 
Find current selection 


Print selection or (if no selection) entire 
script (same as Print button) 


Close script without saving changes (same as 
Cancel button) 


Paste Clipboard contents at insertion point 
Cut selection to Clipboard 


Close script and save changes (same as OK 
button) 


Wrap line without return character (“soft” 
return—symbolized by — in scripts. Don’t 
use a “soft” retum inside quotation marks.) 


Retum character—indicates end of HyperTalk 
statement 


Format script 
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More experiments with 
visual effects 
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You can make some test buttons on Card 1 of your practice stack to try out 
some of the visual effects. These test buttons will demonstrate the effects 
without your having to move to another card. 


Here’s a list of HyperCard visual effects: 


barn door close/barn door open 
checkerboard 

dissolve 

iris close/iris open 

plain (same as no effect) 

scroll down/scroll up 

scroll left/scroll right 
venetian blinds 

wipe down/wipe up 

wipe left/wipe right 

zoom close/zoom open 

zoom in/zoom out (sameas zoom close/zoom open) 


Some visual effects have a more noticeable effect than others, depending on 
the context. For example, the scroll effect creates a clearer transition 
than wipe does when only a few elements change from one card to 
another. Wipe is most effective when two cards have very different 
appearances. Checkerboard and venetian blinds canhavean 
entertaining or humorous effect. 


Barn Door 


To try outthe barn door effect, make a card button and write a script 
for it by following these steps: 


1. Create a new button. 


You want this button on the card, so you don’t have to switch to the 
background. Choose the Button tool, hold down the Command key, and 
drag. Make the button wider than it is high. 


. Double-click the button with the Button tool to get to its 


Info box. 


The Button Info box for the new button appears. Notice that this 
button is a card button, not a background button; it will appear only on 
Card 1. 


. Name the button Barn Door 


Its name will be the same as the visual effect it demonstrates when 
clicked. 


Select these options: “Show name,” “Auto hilite,” and 
“round rect.” 


. Click the Script button to go to the script editor. 


The insertion point should be blinking between on mouseUp and 
end mouseuUp. 


. Type these statements, pressing Return after the first two lines 


(but not after the last line): 


visual effect barn door close to gray 
visual effect barn door open to card 
go to this card 


By the way: The word effect is optional after visual. You can 
leave it out and the command will still work. 


. Click OK to close the script editor. 


If the name is too big for the size of the button, drag the corner of the 
button to make it larger. 


. Choose the Browse tool and try out the new button. 


You should see gray “doors” close and then open onto the same card. 
(This example is only one way to use the barn door effect; you 
don’t necessarily have to pairthe open and close versions.) 
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The visual command must be accompanied bya go command—the 
statement go to this card satisfies the requirement, even though 
it doesn’t take you anywhere. (More specifically, it takes you to where you 
already are.) 


The phrases to gray and to card determine the image HyperCard 
uses during transition. You can use any of the following words for the image: 


black 

card (the image of the destination card) 
gray (or grey) 

inverse (reverses the card image) 
white 


Dissolve 
Create another button to test the dissolve effect: 


1. Create a new button and name it Dissolve 


Follow the same steps and choose the same settings as you did for the 
Barn Door button. 


2. Click Script to see the script editor. 


3. Type the following lines: 


visual dissolve slowly to black 
visual dissolve slowly to white 
visual dissoive slowly to card 
go to this card 


4, Click OK, switch to the Browse tool, and try the button. 


You should see the image fade to black, fade to white, and then fade to 
the card image. 


When creating a stack for your own use or for others, you can combine a 
number of effects to give different visual impressions; for example, zooming 
in on a subject, turning pages, or changing the scene completely. 


Create other test buttons on Card 1 as you like. Using to black or 
to gray as the image will help you see some effects more clearly. 


The syntax of the Visual 


command 


Syntax is a description of the way in 
which words are put together to 
form meaningful phrases. All 
languages—for people and for 
computers—have rules of syntax. 


You've seen several versions of the visual command. Each version 
follows a certain general structure, which may include optional elements. 


An expression of the general, underlying structure that a given command 
must follow is called its syntax. Knowing a command's syntax is as 
important as knowing its name and what it does; however, you don’t have 
to try to memorize syntax just now; you can refer to this section whenever 
you need to. 


Here’s the syntax of the visual command: 
visual [effect] effectName [speed] [to image] 


Optional elements are shown enclosed by square brackets. (You do not 
include the brackets in an actual command.) Words in italic are placeholders: 
for example, in an actual command, you would replace effectName with any 
of the actual effectnames: barn door, checkerboard, zoom, and 
so on. The same would apply for speed and image. 


A statement’s syntax shows you the correct order for elements in the 
statement; for example, if you were to write this command: 


visual fast dissolve 


HyperCard would not be able to understand the command because the speed 
element is in the wrong place. The correct order is 


visual dissolve fast 


HyperTalk syntax is much like English syntax, which makes HyperTalk an 

easy language to use. It’s not always true, however, that a statement that 
makes sense in English will make sense in HyperTalk. Incorrect syntax will 
cause a “Can’t understand” message; in such a case, check the statement’s 

syntax if you find no spelling errors. 


The Appendix and the Quick Reference Card both contain a list of HyperTalk 
commands showing their syntax. 
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Some sound effects 


Two HyperTalk commands cause sound: the beep command, which 
causes the usual Macintosh system beep, and the play command, for 
adding other sounds and music. 


‘\ Important To hear sounds, you must have the Speaker Volume in the Control Panel set 
to a value greater than zero. 


To use the beep command with a button, you would write a script 
like this: 


on mouseUp 
beep 
end mouseUp 


You can cause multiple beeps by adding a number after the command, as in 
beep 3. If you don’t adda number, you get a single beep. In Chapter 3 
you'll use this command when you create an alert box. 


The play command lets you add music to scripts; you can specify a 
number of notes with different pitches and time values and thus make a 
melody play, or you can use digitized sounds (sounds recorded in a digital 
format that computers can understand). Make a new button to try out the 
play command: 


1. Create a new card button on Card 1 and name it Sound 


Use the Command-drag shortcut with the Button tool as usual. Bring up 
the Button Info box by double-clicking the button, type the name, and 
choose the “Show name,” “Auto hilite,” and “round rect” options. 


2. Click the Script button to see the script editor. 
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The syntax of the 
Play command 


3. Complete the script by typing this line: 
play “Harpsichord™ “ec &¢ g g a a g” 


Be sure to include the quotation marks with the instrument name and 
the series of letters representing notes. Also be sure to separate the 
letters with spaces. 


4, Click OK. 


Now try the button with the Browse tool. You should hear the first line of a 


familiar childhood tune. 


The play command allows you to control pitch and tempo as well as 
voice. Here’s the command's basic structure; refer to it as needed: 


play "voice" [tempo tempoValue] ["notes"] 


Voice is either harpsichord or boing, which are included with 
HyperCard, or the name of a digitized sound from some outside source. 


You can optionally set the tempo (speed of play) by including the word 
tempo followed by a number (tempoValue). The value 100 is a medium 
speed; higher numbers play faster. If you don’t specify a tempo, tempo 
100 is assumed. 


Notes make up the melody sequence. (If you don’t specify any notes, 
HyperCard plays a single note in the voice you specify.) You should include 
quotation marks around the voice and the notes. For example, 


play "boing" tempo 200 "e4q dcdee eh" 
plays “Mary Had a Little Lamb.” 
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Specifying the notes 


Notes are represented by the letters A through G, corresponding to Western 
music notation. You don’t have to capitalize the note names. You can include 
further modifiers after the note name, such as an accidental (a sharp or flat), 
an octave specification, and a duration code. Here’s the syntax for a note: 


noteName [accidental] [octave] [duration] 
Accidental is either # for sharp or b for flat. 


Octave is a whole number that specifies the pitch range. For example, g#4 
would be the G-sharp note in the middle range, or what musicians call the 
middle-C octave. Higher numbers give higher ranges, and vice versa. If you 
don’t specify a number, HyperCard uses 4. 


Duration is a letter code indicating how long to hold the note before the next 
note sounds. Here are the codes for note duration: 


whole note (four counts) 
half (two counts) 

quarter (one count) 

eighth (one-half count) 
16th (one-fourth count) 
32nd (one-eighth count) 

x 64th (one-sixteenth count) 


tn 0 QP se 


If you don’t specify a duration code, HyperCard assumes a quarter note. 


A period (. ) after the duration code indicates a dotted note, which means a 
note with a duration value of half again as much; that is, w. would indicate 
six counts (four plus half of four). A numeral 3 after the duration code 
indicates a triplet. 


The codes for octave and duration carry over to subsequent notes unless you 
change them; this feature saves you from having to type numbers and letters 
over and over. (See “Mary Had a Little Lamb,” shown earlier.) 


Here are some examples of notes with modifiers: 


Note 

specification Meaning 

d#5w D-sharp above high C held 
for four counts 

Bb4q B-flat above middle C held 
for one count 

e5h. E above high C held for three 


counts (because of the period 
after the duration code h) 


Even if you have no formal music training and all these terms seem 
mystifying, you can still make melodies with the play command. The 
best way to gain an understanding of how to use the notes is to experiment 
with different notes and modifiers on your own. For instance, choose a short 
tune you already know and try to write it out. You can use the script for the 
Sound button you created earlier to test and change the tune until it sounds 
right to you—or create a new button. 


Dealing with long lines 


You can put a long sequence of notes into a script; however, the script editor 
doesn’t wrap lines or let you scroll to see lines that extend beyond the 
window. You can press Return or Option-Return to wrap a long line 
temporarily while you type the notes; however, if you use this method you 
must delete the Returns to “unwrap” the lines when you’re finished or the 
script won’t work properly. The reason is that HyperCard doesn’t understand 
a line break of any sort occurring inside quotation marks. 
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Another alternative is to wrap a long line permanently by inserting a 
closing quotation mark and the double ampersand (¢& &) followed by an 
Option-Return (—): 
on mouseUp 

play "harpsichord" "c cg g" &&-— 

"a ag" 
end mouseUp 


Notice that you must also begin the wrapped line with a quotation mark. 


Just as at the end of the last chapter, you can take a break now if you 
want and come back sometime later. (The same is true for all chapters in 
this guide.) 


What you’ve done in this chapter 


In this chapter you’ve used HyperTalk commands to produce special effects: 
visual effects and sound. You've also added to your vocabulary list. 


Commands 

beep Produces the system beep. You can cause multiple 
beeps by including a number: beep 3. 

play Causes notes to play. You specify the sound and the 


sequence of notes. 

visual [effect] Causes the visual effects you specify. It must be 
followed by the go command. 

Names of sounds 

"hoing” 


"harpsichord" 


Names of effects 

barn door close/barn door open 
checkerboard 

dissolve 

iris close/iris open 

plain (Same as no effect.) 
scroll down/scroll up 

scroll left/scroll right 
venetian blinds 

wipe down/wipe up 

wipe left/wipe right 


zoom close/zoom open (zoom in/zoom out) 


Miscellaneous 

fast A modifier used with visual effects. 

slow[ly] A modifier used with visual effects. 

tempo A word that you use with the play command to 
control the timing of the notes. 

very A modifier used with fast or slow; it means 


“more.” 
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More About Messages 


ARLIER YOU LEARNED ABOUT HYPERCARD SYSTEM MESSAGES—INFORMATION 
about system events such as clicks (mouseUp), keyboard actions, and 
events in HyperCard (openCard). System messages are sent constantly 
while HyperCard is running. There’s even a message for when nothing is 
happening: idle. (See the Appendix for a list of HyperCard system 


messages.) 


A script, as you’ve seen, can contain instructions to be carried out when a 
particular message is received—in other words, the script “handles” the 
message. Thus, a complete set of instructions that deal with a particular 
message is called a message handler. Message handlers always begin with 
the word on and end with the word end, and both words are followed 
by the name of whatever message the handler deals with; for example, on 


mouseuUp. 
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An object’s script might contain a number of handlers, each one handling a 
different message. Strictly speaking, then, the word script refers to 
everything that appears in the script editor for a given object, and not just to 
a single handler. 


** By the way: On and end belong to a group of HyperTalk words 
called keywords. 


In this chapter you'll write new handlers and explore the way messages travel 
between objects. 


Sending messages 


When someone clicks an on-screen button, the action generatesa mouseUp 
system message. The mouseUp message always goes first to the button 
that was clicked. If that button’s script doesn’t have a handler for 
mouseUp, the message is passed to the card, then to the background, then 
to the stack, then to the Home stack, and finally to HyperCard itself. This 
sequence is called the message-passing hierarchy or the object hierarchy; 
it’s illustrated in Figure 3-1. 
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= Figure 3-1 A message moving through the object hierarchy 
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Create a “Receiver” button 


You can place handlers at different levels. Where you place a handler has an 
effect on its availability. For example, in Chapter 1, when you wrote the 
handler to label all cards of your practice stack, you placed it in the stack 
script; that placement meant that the handler was available for every card in 
the stack. By contrast, if you had placed the handler in the script for one of 
the cards, it would have been available only to that card; no other cards would 
have been labeled. 


Messages can come from the system, from your actions with the mouse, 
keyboard, or Message box, or even from handlers themselves. In this section 
you'll see how messages move around in HyperCard. First, you'll make a 
button to receive a message and then send the message to it in various ways. 
Later, you'll move the receiving button’s handler to different levels in the 
object hierarchy and observe the difference in the handler’s action. 


First, if you left HyperCard after the last chapter, start it up again and go to 
your practice stack. 


Create a new button with the steps that follow; you'll put a handler into this 
button’s script and send messages to it. 


1. Go to Card 2 of your practice stack. 


You can think of Card 1 as your special effects card. Card 2 can be your 
message experiments card. 


2. Create a new card button and name it Receiver 


You don’t need to switch to the background because this is a card 
button. 


Follow the procedure you’ve used in previous chapters: use the Button 
tool and Command-drag to create a new button. Double-click the button 
to see its Info box. Type the name in the Button Name box at the top of 
the Info box. 


3. Select “Show name,” “Auto hilite,” and “round rect.” 
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Send a message with the 


Message box 


4, Click the Script button to see the script editor. 


5. 


o, 
~ 


Type this line between on mouseUp and end mouseUp: 
play "harpsichord" tempo 80 "c4 e g" 
As you can see, this statement will cause three notes to play. 


Alternative for hearing impaired people: If you can’t hear notes, type 
this line in place of or in addition to the play statement to see the 
effect of the handler: 


flash 3 


This command causes the entire screen image to flash rapidly three times 
when the button is clicked. (The white parts of the card switch to black 
and the black parts to white; then they change back again.) 


. Click OK when you're finished. 


The script editor closes and you're back to the card. 


. Change to the Browse tool and try the button. 


Notice that the button becomes highlighted when you click it (because 
of the “Auto hilite” setting) and the notes play immediately. You'll use 
highlighting to distinguish between the sources of messages. 


In the next section, you'll send mouseUp without clicking. 


You can send the Receiver button a message using HyperCard’s Message box: 


1. 


Press Command-M to see the Message box. 


You may see text in the box already. The old text will be replaced by new 
text as soon as you start typing. 


. Type this sentence into the Message box: 


Send mouseUp to button "Receiver" 


Sending messages 


3. Press Return. 


You should hear the notes play immediately; but notice that the button 
does not become highlighted. (To send the message again, just press 
Return.) 


The “Auto hilite” option causes a button to become highlighted when it’s 
clicked. Because you sent mouseUp from the Message box and not by 
clicking, the button didn’t become highlighted. The mouseUp handler still 
responds to the message, however, and the notes play. 


4, Click the close box to hide the Message box again when you're 
finished. 


You can send messages to specific objects from the Message box—and also 
from handlers—using the send keyword. Messages sent with send go 
directly to an object, bypassing the object hierarchy. 


Follow these steps to make a button with which you'll send a message from 


Create a “Sender” button |. 
inside a handler: 


1. Create another card button anywhere on the card and name it 
Sender 


Use Command-drag with the Button tool selected to make the button, 
then double-click the button to see its Info box and type the name in the 
Button Name box. 


2. Select “Show name,” “Auto hilite,” and “round rect.” 
3. Click the Script button to see the script editor. 


4, Type these lines between on mouseUp and end mouseUp: 


send mouseUp to button "Receiver" 

wait 1 second 

set hilite of button "Receiver" to true 
wait 1 second 

set hilite of button "Receiver" to false 
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5. Press Tab to format the script if necessary. 


On mouseUp and end mouseUp should line up at the left edge of 
the window; all the other lines should be indented. 


In English this script says 


“When this button is clicked, senda mouseUp message to the Receiver 
button. Wait one second, and then highlight the Receiver button. Wait one 
second, and remove the highlighting. That’s all.” 


6. Click OK when you're finished. 


7. Change to the Browse tool and click the Sender button. 


The Sender button becomes highlighted when you click it, because of its 
own “Auto hilite” setting. You should hear the notes play as the Receiver 
button responds to the mouseUp message. After a one-second delay, 
you should see the Receiver button become highlighted. After another 
second the highlighting disappears. 


If something else happened, check the Sender button’s script for typing 
errors. 


The Sender button’s handler not only sendsa mouseUp message to the 
Receiver button, but it also uses the set command to cause HyperCard to 
change the Receiver button’s highlighting, and the wait command to 
create a one-second delay—a sort of “delayed reaction” effect. 


The section entitled “Syntax Summaries” at the end of this chapter describes 
the syntax and uses of set, wait, and other commands you'll learn in 
this chapter. 
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Remove the handler from 


the button script 


Every object has a script, even if 
there’s nothing in it. Scripts with 
nothing in them are called empty 
scripts. 


What the message-passing hierarchy means to you is that you can control 
whether your handlers act very locally, say, only for a particular button, or 
more globally, for an entire card, background, or stack. 


In this section, you'll move the mouseUp _ handler of the Receiver button 
to different levels in the object hierarchy to experience the change in its 
response. 


First, notice how the handler works only if you click the Sender button or the 
Receiver button. If you click anywhere else on the card, you won't hear the 
notes play. Furthermore, if you go to another card in the stack and click 
something, you won't hear the notes either. Try it out; when you're finished, 
go back to Card 2. The next step is to move the handler somewhere else. 


Follow these steps to cut the handler from the Receiver button’s script, 
placing it on the Clipboard automatically: 


1. Press Command and Option and click the Receiver button with the 
Browse tool to see its script editor. 


(You can also use Shift-double-click with the Button tool.) 


2. Press Command-A to select the handler. 
Command-a selects the entire script, but in this case there’s only one 
handler in the script. 

3. Press Command-xX to cut the handler and place it on the 
Clipboard. 
The script editor should now have nothing in it. If you still see the 
handler there, try steps 2 and 3 again. 

4, Click OK. 
The script editor disappears and you're back to the card. 


The script for the Receiver button is now empty. You can test it by clicking 
it with the Browse tool. You should see the Receiver button flash (because of 
“Auto hilite”), but hear no sound. 
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Move the handler to the 


card level 


Now, you can paste the handler into the card’s script. 
1. Choose Card Info from the Objects menu. 


2. Click the Script button in the Card Info box to see the card’s 
script editor. 


The top line of the script editor tells you that it’s the script for the card. 


“* Keyboard shortcut: You can press Command-Option-C to see the script 
editor of the current card without having to go through the Info box. 
(This shortcut doesn’t work with HyperCard versions earlier than 1.2.) 


3. When you see the script editor, press Command-V to paste the 
handler. 


4, Click OK. 


5. Test the effects. 


Switch to the Browse tool. First, click the Receiver button; you should 
see no difference in what happens: the button becomes highlighted and 
the notes play. The mouseUp message passes through the empty 
button script and goes on to the card script. 


Now, click the Sender button. Again, you should hear the notes, and then 
see the Receiver button become highlighted and then change back. The 
notes play because the mouseUp message from the Sender button 
also goes through the empty button script to the card script. 


And now, click anywhere on the card (except on another button or in the 
field). The notes play because whenever you click the card, mouseUp 
goes directly to the card, which now contains the handler for mouseUp 
in its script. 
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Move the handler to the 


background level 


Take the handler out of the card script and move it to the background script: 


1. 


Choose Card Info from the Objects menu again and click Script to 
see the script editor. 


Or, you can simply press Command-Option-C. 


Press Command-A to select the handler. 


. Press Command-X to cut the script and place it on the Clipboard. 


The card script should now be empty. 


Click OK. 


. Choose Bkgnd Info from the Objects menu and click the Script 


button to see the background’s script editor. 


Keyboard shortcut: You can press Command-Option-B to see the script 
editor of the current background. (This shortcut doesn’t work with 
HyperCard versions earlier than 1.2.) 


. Press Command-V to paste the handler. 
. Click OK. 


. Test the effects. 


Using the Browse tool, click the Receiver button, the Sender button, and 
the card, just as before. You should hear the notes play in every case. The 
mouseUp message goes through the empty Receiver button script and 
empty card script to the background script, which now contains the 
handler. 


Now, move to any other card in the stack and click any area except a 
button or field—you should still hear the notes play. The handler is now 
available to any card sharing the background. 
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Change the handler 


If you moved the handler to the stack level, the same thing would happen 
because this practice stack has only one background; however, in cases where 
a stack has more than one background, only a handler at the stack level or 
above would be available to all cards of all backgrounds. 


¢ 


Other handlers intercept messages: The reason you don’t hear the notes if 
you click one of the travel buttons or other buttons besides Sender and 
Receiver is that those buttons already contain mouseUp handlers. Once 
a message is handled, it’s not passed on unless you specifically pass it 
using the pass keyword. 


¢ 


If you were to leave the mouseUp handler where it is, in the background, 
you’d hear notes any time you happened to click somewhere other than a 
button. You can do one of two things: take the handler out of the 
background and move it back to the Receiver button; or change the handler’s 
name from mouseUp to something else—in other words, change the 
handler so that it no longer responds to mouseUp, but to some other 
message. These steps show you how to do the second alternative: 


1. Open the script editor for the background by choosing Bkgnd 
Info from the Objects menu and then clicking the Script button. 


Or, simply press Command-Option-B. 


2. Select the word mouseUp in the first line of the handler. 


Drag across the word as you would when selecting any text—or just 
double-click the word. 


3. Replace it by typing the word playTune 


PlayTune serves as the alternative name. You could use any other 
word (except a HyperTalk keyword); this name seems appropriate 
because it describes the action of the handler. 


“+ By the way: If you are using the flash 3 alternative instead of the 
notes, you could use a different name, suchas razzleDazzle (but 
don’t use flash). Be sure, however, that you use your alternative name 
in the steps that follow. 
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4, Select the word mouseUp in the last line of the handler. 


5. Replace it also by again typing the word playTune 
The name used after on must match the name after end. 


You have now changed the handler froma mouseUp handler to a 
playTune handler. It will no longer respond to the mouseUp message, 
but instead to the message playTune. But where doesa playTune 
message come from? 


The answer is that you'll put a new handler in the Receiver button’s script. 
The new handler willsenda playTune message: 
6. Click OK to save the handler and close the script editor. 


You're back to the card again. 
7. Go to Card 2 (if you aren’t already there). 


8. Open the script editor for the Receiver button. 


Use Option-Command-click with the Browse tool, or Shift-double-click 
with the Button tool. 


You should see the on mouseUp and end mouseuUp lines 
already in the script editor. HyperCard always adds the lines to “empty” 
button scripts for your convenience. 

9. Type the following word between the two lines: 
playTune 
The completed handler should look like this: 


on mouseUp 
playTune 
end mouseUp 
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10. Click OK to save the handler and close the script editor. 


11. Test the effects. 


Clicking the Receiver button or the Sender button with the Browse tool 
should have the same effect as it did before you moved the handler. 
Sending mouseUp from the Message box to the Receiver button 
should also work the same. But clicking anywhere else on the card won't 
cause the notes to play, because the background handler isn’t a 
mouseUp handler any more. 


Now, when the Receiver button receives mouseUp, its handler in turn 
sends the message playTune. That message goes down the hierarchy 
until it’s intercepted by the playTune handler in the background script. 
The playTune handler contains the command that plays the three notes. 


Try this: go to some other card, open the Message box (press Command-M), 
type the word playTune and press Return. You'll hear the notes because 
the Message box sends the word as a message along the hierarchy until it 
reaches the background script. 


(If you wanted to send playTune to some object not in the hierarchy, 
you would use the send keyword to specify the destination; otherwise, 
using just playTune alone is sufficient.) 


Close the Message box when you've finished experimenting. 


It’s a new command 


What you've done in this section is essentially define a new command, which 
isnamed playTune. The playTune command plays three notes. 
That’s really all there is to defining your own commands: think of what you 
want a command to do, think of a name for it, and write a handler that uses 
the name after on and end, with the appropriate HyperTalk statements 
in between. Then, to make the command work, send the name as a message 
to the object that has the handler in its script. 


‘ By the way: It’s generally best to avoid using the name of an existing 
HyperTalk command or function as the name of a command you create. 
See the HyperCard Script Language Guide for details on naming 
commands. 
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A disappearing act 


Confirming actions 


Sometimes it’s useful to be able to put a message on the screen and get a 
confirmation for an action someone has taken. For example, the Macintosh 
system software gives you a chance to change your mind before erasing a 
disk by putting an alert box on the screen in which you confirm your choice. 
You can make your own alert boxes in HyperCard using a HyperTalk 
command. In this section you'll learn how to do it. 


Go to Card 2 of your practice stack if you are not there already; then follow 
the steps below. 


1. Switch to the Button tool and create a new button on Card 2; name 
it Disappear 
Use Command-drag with the Button tool as before and double-click to 


see the Button Info box. Type the name in the Button Name box. 


2. Select the usual “Show name,” “Auto hilite,” and “round rect” 
options. 


3. Click Script to see the script editor and type this line between 
the existing lines: 
hide me 
The HyperTalk word me always refers to the object that contains the 
handler—in this case, the button itself. 


4, Click OK. 


5. Switch to the Browse tool and click the Disappear button. 


When you click this button with the Browse tool, it. . . disappears. 
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A command to put up 
an alert box 


To get the button back again, 
1. Press Command-M to see the Message box. 


2. Type this statement and press Return: 
show button "Disappear" 


“ By the way: Once you've typed a statement into the Message box, it stays 
there until you type something else—even if the box is invisible. All you 
need to do to send the message to HyperCard again is to press Return. 


You can use the hide command to make invisible a field, a button, a 
window (such as the Message box), the menu bar, the background picture 
(graphics in the background), or the card picture (graphics on the card that 
aren't in the background). The show command does just the opposite; you 
use show to reveal hidden elements. 


Next, you'll create an alert box that will appear whenever you click the 
Disappear button. 


Suppose you wanted anyone using your stack to think twice about making 
the button disappear. You can write a handler to make sure that happens: 


1. Open the script editor for the Disappear button. 
Use Command-Option-click with the Browse tool or Shift-double-click 
with the Button tool. 


2. Click after the word mouseUp in the first line to place the 
insertion point, and then press Return to start a new line. 


3. Type the following lines: 


beep 
answer "Do you really mean that?" with "Yes" or "No" 
if it is "Yes" then 


4, Click before end mouseUp to reposition the insertion point 
at the beginning of the last line. 
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5. 


Type this line and press Return: 
end if 
Here’s what the complete handler should look like: 


on mouseUp 
beep 
answer "Do you really mean that?" with "Yes" or "No" 
if it is "Yes" then 
hide me 
end if 


end mouseUp 


If you have extra blank lines, you can delete them, although they won’t make 
a difference in how the handler works. Press Tab to format the script, if 
necessary (the lines indent automatically). 


6. 


re 


° 


Click OK. 


Click the Disappear button with the Browse tool. 


When you click the Disappear button now, you should hear a beep and 
then see the alert box shown in Figure 3-2. 


Figure 3-2 The alert box you created with the Answer command 


Something else happened? If you get a “Can’t understand” message 
instead, go to the button’s script and check the typing. Make sure that no 
lines are left out and that the lines are in the correct order. Then try again. 
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In the alert box you have the choice of clicking a Yes button or a No button. 
These labels will be whatever you specify in quotation marks in the 

answer command statement. You can have up to three choices. Whichever 
choice you put last in order will be the button farthest to the right with the 
extra dark border; use this place for the the “best” or “safest” choice—the 
choice that can do no damage. This farthest-right button is also the one 
chosen by pressing Return or Enter. 


8. Click No so the button doesn’t disappear. 


If you click Yes by mistake, just press Return; your message to show the 
button should still be in the Message box. 


9. Go to the script editor for the Disappear button. 


Use Command-Option-click with the Browse tool or Shift-double-click 
with the Button tool. 


The handler includes directions for what HyperCard should do if the Yes 
button is clicked: 
if 2b 2s “Yes then 
hide me 
end if 


The word it refers to the label of whatever button you click. (The word 
it hasa specific identity in HyperTalk; you'll learn more about it in the 
next chapter.) If you click Yes, then HyperCard follows the instructions to 
hide the Disappear button (me), because that’s what the directions say to do. 
If you click No, HyperCard skips the instructions, so the Disappear button 
isn’t hidden. 


In English, the complete script says 


“When this button is clicked, sound the system beep and let the user answer 
the question ‘Do you really mean that?’ by clicking either a button labeled 
‘Yes’ or a button labeled ‘No,’ with ‘No’ being the emphasized choice. If the 
answer is ‘Yes,’ then make this button invisible. That’s it, and that’s all.” 


You can use a similar handler anytime you want to provide choices for 
yourself or other people using a stack. 
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An additional action 


Every button can result in a different action. So far, you've specified an action 
for the “Yes” choice; next, you'll specify one for “No.” The script editor of the 
Disappear button should still be on your screen. 


1. Click before end if to position the insertion point at the 
beginning of the next to last line. 


2. Type the following lines (press Return after each line): 


else 
answer "Glad you reconsidered." with "No problem" 


The lines will automatically indent. When you press Return for the final 
time, end mouseUp should line up at the leftmost margin. 


Here’s how the completed handler should look in the Disappear button 
script: 


on mouseUp 
beep 
answer "Do you really mean that?" with "Yes" or "No" 
if it is "Yes" then 
hide me 
else 
answer "Glad you reconsidered." with "No problem" 
end if 
end mouseUp 


If everything looks correct, 


4, Click OK. 


wa 


Try the Disappear button. 


Now, when you click the Disappear button with the Browse tool you 
get the beep and the alert box just as before. Clicking Yes causes the 
button to disappear. Clicking No (the choice represented by else) 
makes another alert box appear with a gratuitous comment and reply— 
just for fun. (No further instructions are specified for the “No problem” 
button.) 
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If, then, and else are HyperTalk keywords that work together in 
specific arrangements called if structures. If structures are used to test 
things and to specify different actions, depending on the results. You 
included an if structure in the handler for the Disappear button: 


If structures 


if it is "Yes" then 

hide me 
else 

answer "Glad you reconsidered." with "No problem" 
end if 


An if structure in HyperTalk is used much the same way as statements 
beginning with “if” are used in English. For example, in English you might say 
“If I am hungry, then I'll eat dinner.” The phrase “I am hungry” is the thing 
being tested; if that’s true, an action is specified, namely “I'll eat dinner.” 


If structures come in a few varieties; two of them are shown here. The 
first version is much like the structure you first used to hide the Disappear 
button: 


if condition then 
action 
end if 


The placeholder word condition stands for the thing being tested. The word 
action stands for the instruction lines that follow if the condition is true. 
The last line, end if, signals the end of the instructions. Here’s how the 
English example would look if it could be written in HyperTalk form: 


if Tamhungry then 
I'll eat dinner 
end if 
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Another type of if structure specifies an alternative action to take if the 
condition is not true. It has this general form: 


if condition then 
action 

else 
anotherAction 


end if 


In this version, the placeholder word anotherAction stands for an alternative 
instruction line or lines. An example in English might be something like this: 
“If Iam hungry, then I'll eat dinner; otherwise [else] I'll go to the movies.” 
Here’s how it would look if it could be written in HyperTalk: 


if Tamhungry then 
I'll eat dinner 
else 
I'll go to the movies 


end if 


This structure is the one you used in the final version of the handler for the 
Disappear button. 


If structures are useful anytime you want to make the action HyperCard 
takes dependent on some choice or condition. For more information on if 
structures, see the HyperCard Script Language Guide or other books on 
HyperTalk. 


What you’ve done in this chapter 


You've done a lot. You've learned about HyperCard’s message-passing 
hierarchy and seen how placement of handlers can affect the range of their 
actions. You've also used the if structure—a useful structure for taking 
action in a specific case or condition. 


See the following reference section, “Syntax Summaries,” for the syntax of 
each command and for the send keyword. 
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Here are the terms you've added to your vocabulary: 


Commands 


answer 


flash 


hide 


set 


show 


wait 


Keywords 


else 
end 


end if 


Lt 


on 


send 


then 
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Puts a box on the screen containing a question and 
up to three response buttons. 


Causes the card image to flash. It’s an external 
command (sometimes called an XCMD for short) 
included with HyperCard. External commands are 
written in a language other than HyperTalk. 


Makes buttons, fields, windows, and pictures 
invisible. 


Changes the value of HyperCard properties. (See the 
syntax section for this command for an explanation 
of properties.) 


Causes hidden buttons, fields, windows, and 
pictures to become visible. 


Causes HyperCard to wait for a specified length of 
time or until some specific action occurs. 


A word used when you want to specify an 
alternative action inan if structure. 


You first encountered this keyword in Chapter 1; it 
signals the end of a handler or structure. 


The last statement of an if structure. 


The keyword that begins special structures called 
if structures. 


You first encountered this keyword in Chapter 1. All 
handlers begin with on. 


Sends messages to objects directly. It works in the 
Message box as well as in handlers. 


A keyword used in if structures to mark the 
beginning of a list of actions to be carried out. 


Answer 


Properties 


hilite A button property; if its value is true the button 
is highlighted. 

Miscellaneous 

al The place where the answer command puts the 
label of the button chosen. 

second A unit of time; you could also abbreviate itas sec. 

with A preposition; used inthe answer command and 


some other commands. 


Syntax summaries 


This section describes the syntax (most generalized form) of the send 
keyword and each command you used in this chapter. 


You don’t have to try to memorize these statements; refer to them as 
needed when writing your own handlers. 


The basic structure for answer is this: 
answer “question” [with "reply" [or “reply2" [or "reply3"]]] 


Question can be any statement you like—usually a question invites the user 
to answer. Reply, reply2, and reply3 are the labels for buttons representing the 
choices. The quotation marks are required. 


You can have as many as three different replies. If you don’t specify a reply, 
HyperCard displays a single OK button in the box. The size limit for a reply is 
13 characters, depending on the width of the characters. 


The label of whatever button gets clicked is put into a special place named 
it. Inthe handler you wrote for the Disappear button, the action of the 
if structure evaluated what it was (that is, which button had been 
clicked). You'll learn more about it in Chapter 4, “Fields, ‘It,’ and Other 
Containers.” 
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Hide 


Send 
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Here are the four structures of the hide command: 


hide menuBar 
hide windowName 
hide object 
hide picture 


MenuBar is, obviously, the HyperTalk name for the menu bar. 
WindowName stands for the card window, one of the palettes (Tools or 
Patterns), or the Message box. Replace windowName with one of these 
names: 


card window 

tool window 
pattern window 
[the] message [box] 


Object is the name or description of a button or field; for example, 
background button 1. Pictureiseither card picture, forall 
elements on the card level created with a Paint tool, or background 
picture, for graphic elements on the background level. 


See also the section “Show” later on. 


The syntax of the send _ statement you used is 
send "messageName" [to object] 


The quotation marks around the name of the message aren’t needed if the 
message is a single word, like mouseUp. Object is an identifier for any 
object, such as its number, ID, or name. If you use the name, you must 
enclose it in quotation marks. 


Send directs a message to any object in the current stack or to another 
stack, but not to a specific object in another stack. The send keyword 
sends a message directly to the specified object, bypassing any other objects 
in the usual message-passing hierarchy. 
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Set 


Show 


The general structure of the set command is 
set [the] property [of object] to value 


Property stands for a changeable characteristic of the HyperCard environment 
or of an object. For example, the user level is a property of HyperCard; the 
statement set userLevel to 5 within a handler or typed into the 
message box would set the user level to Scripting (value 5). Object is an 
identifier for an object, such as its number, ID, or name. 


What value is depends on the property. Some properties, such as hilite, 
have the values true or false. Others,suchas userLevel, have 
numeric values. Still others—such as the name _ property of a button—have 
as their value a string of characters. 


Examples of properties you can change using set are the button style, the 
name of any object, a pattern from the Patterns palette, and many others. A 
complete description of properties is beyond the scope of this book, but the 
Appendix contains a complete list of properties. 


The show command, like the hide command, has four versions: 


show menuBar 

show windowName [at h,v] 
show object [at h,v] 
show picture 


See “Hide,” earlier in this section, for a description of the placeholders. In the 
optional phrase at h,v the his a number specifying horizontal location on 
the screen, and the v specifies vertical location. The two numbers are 
separated by a comma. This optional phrase lets you place the window or 
object wherever you want. If you don’t include it, the window or object 
appears wherever it was before it was hidden. 


Later on, in Chapter 5, you'll learn more about the horizontal and vertical 
screen coordinates. 


Syntax summaries 71 


Wait 
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The wait command can have any of three forms, depending on what you 
want it to do: 


wait [for] number [seconds] 
wait until condition 
wait while condition 


Number is a whole number. If you want seconds, you must add second, 
seconds, or the abbreviation sec or secs; otherwise, HyperCard 
uses ticks, which have a value of 0 second. No other measurements (such as 
minutes) can be used. 


In the second and third forms, condition is some state that has the value 
true or false. Inthe second form the command waits until the 
condition has the value true. In the third form, the command waits while 
the condition has the value true. 
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C H A F I E R 4 


Fields, “It,” and Other Containers 


N EVERYDAY LIFE, A CONTAINER IS SOMETHING YOU CAN PUT THINGS INTO. IN 
HyperTalk, a container is a place in the computer’s memory where you can 
put something of value, such as text or numbers. You can then get whatever 


you have put into a container and use it elsewhere as needed. 
In this chapter you'll learn about different kinds of containers, and you'll see 
how handlers can work with values in containers to do such things as 


calculations. 


As in previous chapters, if you took a break, start up HyperCard and go to 


the practice stack before you go on. 
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/\ Important 


Fields as containers 


Fields are objects—they can receive and send messages and can have scripts. 
Fields are also containers. They usually contain text; specifically, regular (field) 
text rather than Paint text. 


You already used a field as a container in Chapter 1, when you wrote the 
openCard _ handler to label the cards. Here’s the handler (you can also see it 
on the screen if you open the script editor for the stack script): 


on openCard 
put "This is Card" && number of this card into field l 
end openCard 


This handler uses background field 1 to hold a string of characters made up of 
the text string “This is Card” and the card’s number. Every time a card opens, 
this handler puts the same thing, but with a new card number, into field 1. 


If you place a field in the background, it appears on every card sharing that 
background; but the text that field contains can be different on every card. 
An interesting feature of HyperCard is that even though a background field is 
the container for the text, the text itself remains with the card. This feature 
allows you to have card-specific text that appears in the same place and in the 
same style on each card, even though its content changes. 


Deleting a background field deletes all the text for that field on all cards, even 
though the text “belongs” to the cards. Once the text is gone, you can’t get 
it back. 


HyperCard presents an alert box when you use the Cut or Clear commands on 
a background field so that you can reconsider. A 


Although fields are used most often to contain text, they can also hold 
numbers (numeric values). 


“» By the way: Numerals can be interpreted either as numbers or as text, 
depending on what a handler does with them. For example, the handler 
that labels the cards takes the number of each card and combines it with a 
text string. In doing so, HyperCard treats the numeral as text rather than 
as a number. 
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Set up the fields 


The Field tool 


A simple calculation 


In this section you'll create some fields to hold numbers and then write a 
handler that uses those numbers to calculate simple interest on a one-year 
loan. The handler then will put the resultt—amount of interest, total amount 
of loan, and monthly payment—into other fields. No expertise with 
mathematics is required on your part! 


You'll need five fields as containers for the numbers. You'll make card fields 
instead of background fields because you don’t need the fields to be on every 
card of your practice stack. 


Creating the first field 
Follow these steps: 
1. Close the Message box if it is still on the screen. 


2. Go to Card 3 of the practice stack. 


You can use this card for your “field work.” 
3. Choose the Field tool from the Tools menu. 


4. Hold down the Command key and drag to create a new field. 
Make the field about an inch wide and a quarter to half an inch high. 


5. Move the field to the left of center on the card. 


The location isn’t too important now; later you can adjust it. 


6. Double-click the field to see its Info box. 
Notice that this field is card field 1. 


7. Name this field Amount and select “shadow” as the field’s 
style. 
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10. 


. Click the Font button to see the Text Style dialog box. 


. Change the font size to 14. 


This setting will make the numbers in the fields easier to read. The Line 
Height setting automatically changes to 18. 


Click OK. 
The Field Info box closes; the first field should still be selected. 


Copying and naming the other fields 


Instead of creating new fields from scratch, you can just make copies. Be 
sure you make the copies in the order specified so you can keep track of 
which field is which. 


1. 


Position the pointer in the middle of the selected field, hold 
down the Option key, and drag to duplicate the field. 


When you copy the field, HyperCard automatically identifies the copy as 
card field 2. When you release the mouse button, the second field is 
automatically selected. 

Position the copied field below the first one. 

You can drag the field by its center the same way you would a button to 
get it in the right position. 

Double-click the field to see its Info box. 


Name the field Rate 

Type over the name of the first field, which is already highlighted in the 
Field Name box. All other settings are the same as the first field, which is 
just what you want. 

Click OK. 

The Info box closes. 


Repeat the Option-drag procedure on card field 2 to create a 
third field. 
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7. Position the new field 3 on the right side of the card, with some 
space in the middle between it and the first two fields. 


You can adjust the spacing in a moment after you’ve made all the fields. 


8. Double-click the field to see its Info box and name it 
Interest 


9. Click OK. 


10. Repeat the Option-drag procedure with field 3 to make a new 
field 4 below it; name this field Total 


11. Repeat the Option-drag with field 4 to make a new field 5 below 
field 4; name field 5 Monthly 


Your screen should now look roughly like that in Figure 4-1. If you want 
to adjust the position of your fields, go ahead. Leave some room above 
each field so you can type a label. Don’t be too concerned with precise 
placement—the important thing is the scripting practice coming up after 
the next section. 


m Figure 4-1 The five new card fields 


“nn oe -~ Card field “Interest” 


ae Sees en Card field “Total” 
= er Card field “Monthly” 
siete | 


Card field “Amount” 


Card field “Rate” 
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Labeling the fields on the card 


Next, put Paint text labels above each field to help you identify their 
contents. Follow these steps: 


1. 


2. 


The Paint Text tool 


Choose the Paint Text tool from the Tools menu. 


Choose Text Style from the Edit menu to see the dialog box. 


If you are using the menu torn off as the Tools palette, you can just 
double-click the Paint Text tool to see the Text Style dialog box. 


. Select Geneva 12 and, if necessary, click the “Left” button in the 


lower-left corner of the box to align the text to the left. 


Click OK. 
The Text Style dialog box closes. 


. Click just above the first new field to place the insertion point. 
. Type Amount 


. Click above card field 2, which should be the one below card 


field 1. 


. Type Interest Rate 


. Add labels above the other fields as follows: 


field 3 Interest 
field 4 Total Amount 
field 5 Monthly Payment 


Don’t worry about getting the text lined up exactly. The card should look 
something like the one in Figure 4-2. 
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m Figure 4-2 Paint text labels above the five fields 


A calculating handler Next, you'll create a Calculate button and put a handler into its script to make 
use of the fields for the interest calculation: 


1. Switch to the Button tool. 


2. Command-drag to create a new button. 


You can put the button anywhere you like on the card. In the middle 
with fields on each side is one possibility. 


3. Double-click the button with the Button tool. 
The Button Info box appears. 
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4, Name the button Calculate and choose “Show name,” “Auto 
hilite,” and “round rect.” 


6. Click the Script button and type these lines between the 
existing lines: 


set numberFormat to 0.00 

get card field "Amount" 

multiply it by card field "Rate" 
divide it by 100 

put it into card field "Interest" 
add card field "Amount" to it 

Put Lt Ante card fiela “Total” 
divide it by 12 

put it into card field "Monthly" 


The first thing this handler does is change the number format of HyperCard 
to “dollars and cents” (two places to the right of the decimal point). The 
number format is a HyperCard property aptly named numberFormat. 
The set command gives this property the value 0.00 (zeros, not 
letters), which specifies the standard dollars-and-cents format. 


The get command fetches a value from a container—in this case, field 1, 
named “Amount”—and puts the value into another container named it. 
You first encountered it in the last chapter where the answer 
command used the container it as the place to put the label of a clicked 
button. (The button’s label is a text value.) 


It isa handy, ever-present container in HyperCard. You can often use this 
container’s name in commands just as you might use the English pronoun it 
in a sentence, which makes the commands sound natural and easy to 
understand. 
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/\ Important 


As you see, HyperCard can perform arithmetical operations using the value in 
the container it. The result of an operation with it always goes back 
into it, replacing what was there before. 


In English, the handler would say almost exactly the same thing as it does 
now in HyperTalk. The statements perform operations on numbers from 
card fields, using it, and put the results into other card fields. 


The handler as written is not the most elegant way to accomplish the 
calculation. It’s used as an example here because it shows each step of the 
calculation separately. 


7. Check your typing carefully, and then click OK. 


The script editor closes. 


In HyperTalk you must use card or cd infront of field to specify 
a card field. If you leave out card, HyperCard assumes you mean a 
background field. 


Conversely, you must use background, bkgnd, or bg in front of 
button to specify a background button, otherwise HyperCard assumes 
you mean a card button. 


(The abbreviations cd and bg are not available in HyperCard versions 
earlier than 1.2.) A 
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The best way to see how the handler works is to try it by typing some 
Test the handler values into the “Amount” and “Interest Rate” fields and clicking the Calculate 
button. 


Let’s say you want to know the interest, total amount, and monthly 
payments for a one-year loan of $8,000 at 16.5 percent annual simple interest. 


1. Choose the Browse tool. 
2. Click inside the Amount field to set the insertion point. 


3. Type 8000 for the amount $8,000. 
Don’t type the comma or the dollar sign—they will cause an error. 

4, Click in the Interest Rate field and type 16.5 for the interest 
rate. 


Don’t include a percent symbol. 


5. Click the Calculate button. 


Almost instantly, you should see numbers appear in fields 3, 4, and 5. Those 
numbers should be 


Interest 1320.00 
Total Amount 9320.00 
Monthly Payment 776.67 


** Something else happened? If you got different values, no values at all, or 
an alert box, check the script. Make sure that you haven’t left out a line 
and that the handler is free of typing errors. Check that you have the 
fields labeled correctly (look at their Info boxes to verify their names). 
Also be sure that you haven’t put a comma or dollar sign into the Amount 
field or a percent symbol into the Interest Rate field. 


Try some other values for amount and interest rate. (You'll have to select and 
type over the numbers already in the Amount and Interest Rate fields.) Then 
click the Calculate button to see the new results. 
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The handler with 
comments 


on mouseUp 
set numberFormat to 0.00 
get card field "Amount" 


The following version of the handler shows comments that describe the 
action of the handler’s statements. Comments are text lines typed into a 
script that are not part of the instructions. In HyperTalk, a comment must 
be preceded by two hyphens (--); the double hyphens indicate to HyperCard 
that the text following is a comment and should be ignored. 


You do not have to type these comments into your own script; they are 
shown for example only. 


-- Dollars and cents. 


-- The value in "Amount" gets put into It. 


multiply it by card field "Rate" -- The result of the multiplication 


divide it by 100 


-- remains in It. 


-- Because field "Rate" is a percent. 


put it into card field "Interest" -- The amount of interest. 


add card field "Amount" 


-- Note: The Put command puts only the VALUE 
ina of It into the card field. The Put 
as command doesn't empty It. 


-- Interest plus original amount. 


put it into card field "Total" -- And the total amount is still in It. 


divide it by 12 


-- To get monthly payments for one year. 


put it into card field "Monthly" -- The final action. 


end mouseUp 


-- As always. 


Comments typed into the script editor would not look as neat as those 
shown here. In this example, the comments have been formatted for 
readability. 


Although HyperCard ignores comments, other scripters generally appreciate 
them. Adding comments to your scripts is an excellent way to document 
what your scripts do. Comments not only help other scripters understand 
what you've done, but also help you remember, when you look at old scripts 
long after you’ve written them. 


Your comments don’t have to be as elaborate as those in the example. In fact, 
the more clean and elegant your handlers are, the fewer comments you're 
likely to need. 
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The Message box 


An operator is a character or group 
of characters that cause an operation, 
such as addition or subtraction, or 
an evaluation, such as comparison 
of two things. See the Appendix for a 
list of HyperTalk operators. 


The selection 


Other containers 


Other HyperTalk containers are the Message box, the selection, and 
variables. 


You can see the Message box anytime by pressing Command-M. It’s called 
the Message box because you can use it to send messages to HyperCard or to 
objects, as you did in Chapter 3. You can also use the Message box to give a 
one-line command to HyperCard and to search for text. 


The Message box is a single-line container. The put command uses the 
Message box as its destination if you don’t specify any other container. For 
example, typing card field 5 inthe Message box and pressing Return 
would cause the contents of card field 5 to appear in the Message box; the 
same thing would happen if put card field 5 were ina handler. 


You can use the Message box as a calculator by typing numbers and 
arithmetic operators (+, -, *, /) into it—say, 350 - 62. The 
answer, 288, appears in the Message box when you press Return. 


You can also type a HyperCard function into the Message box and press 
Return to see the value of that function. (See “A Few Words About 
Functions” near the end of this chapter for an example.) 


Anytime you select regular text in a field by dragging across it, the part that 
appears highlighted (that is, the selection) is put into a container 
appropriately called the selection. Thecontainer the 
selection can bea destination forthe put command; that is, you can 
use the put command to replace or add to selected text in a field. 


“> By the way: Text located using the HyperTalk find command isn’t 
automatically selected, and therefore is not put into the selection. 
You can get the text located with find, however, by using the 
function the foundText. 
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Variables 


A variable is something that can have any value you choose to give it. The 
values of variables change; by contrast, the values of constants are always 
the same. For example, pi is a HyperTalk constant having the value 
3,14159265358979323846. You create a variable simply by thinking of a name for 
it (you can name it anything you like) and using the name with the put 
command. For example, in a handler you might have 


put 16 into Ham -- "Ham" is the first variable name. 
put 2 into Eggs -- "Eggs" is the second variable name. 
put Ham+Eggs -- Puts 18 into the Message box. 


The name of a variable must start with a letter and can contain any 
combination of letters and numbers plus the underscore character 

(_ ), up to 29 characters maximum length. Operators or special characters can’t 
be used. 


You can use variables to streamline calculation handlers by making them more 
like formulas. Here’s the first part of the handler for the Calculate button, 
using two variables, Amt and Rte, to figure the interest rather than 
using the get command and it. 


set numberFormat to 0.00 

put card field "Amount" into Amt 

put card field "Rate" into Rte 

put (Amt*Rate)/100 into card field "Interest" 


Instead of using the multiply and divide commands, this version 
uses the arithmetic operators * and / to combine the variables on a single 
line. (See the section “Syntax Summaries” later in this chapter for more 
information on arithmetic commands.) 


The container it isa variable. Some HyperTalk commands, such as 
answer and get, automatically change its value. 


“> Local versus global: The variables discussed here are local variables; 
that is, they and their values exist only within the handler in which they’re 
created. HyperCard also has global variables, whose values are available 
to all handlers everywhere. Global variables aren’t covered in this book. See 
the HyperCard Script Language Guide. 
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A few words about functions 


HyperTalk contains both commands and functions. A command carries out 
an action, whereas a function produces a value of some sort. You can use 
names of functions in commands to get values, without having to figure out 
how to write out the formula as part of your handler. A few examples of 
built-in HyperTalk functions are 


average (list) Finds the average of a list of values. The 
values must be inside parentheses and 
separated by commas. 


compound (rate, periods) Finds the value of an account bearing 
compound interest. 


the date Gives the current date. 

the diskSpace Gives the number of bytes of free space. 

the mouseLoc Provides the location of the pointer on 
the screen. 

the sound Gives the name of the sound currently 
playing, or if no sound is playing, gives 
"done" 


You can type a function into the Message box and get a value when you press 
Return. Press Command-M to see the Message box and type these functions: 
the date 

the time 

the diskSpace 

average (17,24,56,52) (The answer should be 37.25.) 


Some functions require the word the. For example, typing date by 
itself into the Message box won't work. 


A thorough discussion of HyperTalk functions is beyond the scope of this 
book. The Appendix and the Quick Reference Card contain a list of all 
HyperTalk built-in functions. 
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What you’ve done in this chapter 


In this chapter you've practiced using fields as containers for numbers and 
written a handler to perform a calculation. You've also learned about other 
HyperTalk containers, such as the Message box, the selection, and 
variables. You've also seen how comments are added to scripts using the 
double-hyphen (--). 


Additions to your word list: 


Commands 

add 

divide 

get Fetches a value and puts it into the variable it. 
multiply 


subtract 


Prepositions 
after 
before 


into 


Properties 

numberFormat A property of the HyperCard environment. You 
change it with the set command. 

Containers 


it An all-purpose variable container used as a 
destination by some commands. 


the selection A container that automatically holds selected 
(highlighted) text. 
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Syntax summaries 


This section contains syntax descriptions of the commands you used in this 
chapter. Use this section for reference as needed. 


The arithmetic commands are add, subtract, multiply, and 
divide. 


add expression to destination 
subtract expression from destination 
multiply destination by expression 
divide destination by expression 


In all four commands, expression is something having a numerical value. 
Destination is a container. 


HyperTalk also includes arithmetic operators that perform calculations: + 
(addition), - (subtraction), * (multiplication), and / (division). For 
example, 


put 3 into it 
add 7 to it 


does the same thing as 
put 3 + 7 into it 


In both cases the result is 10 in it. 
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Get 


The syntax of the get command is 


get expression 


Expression is a description of something having a value; it can be a text string 
or a number. Here are some examples: 


get field 1 

get the name of background button 3 
get the userLevel 

get 7zZ+135 <= puts 85 into It. 


Get puts the value of expression into it. In fact, these two commands 
are identical: 


get field 1 
put field 1 into it 


In fact, anything you might want to do with the get command can 
probably be accomplished just as well with put. For example, the lines 


get the date 
Hue it 


do the same thing as 


put the date 
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Put 
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The syntax of the put command is 
put expression [preposition destination] 


Expression is a description of something having a value; it can be a text string 
ora number. Preposition is either into, before, or after. 
Destination is a container, such as it, a field identifier, or some other 
container. For example, 


put 256 into card field 3 


Into causes anything already in the destination container to be replaced by 
the expression. Before places the expression at the beginning of what's in 
the container (if anything), and after puts the expression at the end. 


If you don’t specify a destination, the expression is put into the Message box. 


Chapter 4: Fields, “It,” and Other Containers 


C H A P T E R 5 


Animation 


ITH HYPERTALK, YOU CAN WRITE COMMANDS THAT RAPIDLY CHANGE THE 
images on the screen, creating animation effects. Animation combined with 
visual effects and sound can turn a presentation, a demonstration, or a 
training stack into an exciting multimedia production. In this chapter you'll 


explore two of the ways to animate images. 
The first kind of animation involves using HyperTalk commands to 
manipulate graphics on a single card; the second kind uses different images 


on a number of cards, which are then shown in rapid succession. 


If you took a break after the last chapter, start HyperCard again and go to 


your scripting practice stack. 
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Animation on a single card 


In HyperCard, anything you can do with a menu command you can also 
accomplish with a HyperTalk command in a handler. You can achieve an 
animated effect by writing a handler to select a picture and cause it to move. 


The first step is to create a graphic image to animate. The one you'll make 
next is simple to do using the Paint tools. You might want to tear off the 
Tools menu and work with it as a palette so you can switch tools more 
easily. 


Make something 
to animate 


Drawing a circle 
Circles are easy to make with the Paint tools. Follow these steps: 


1. If the Message box is visible on the screen, close it by pressing 
Command-M or clicking its close box. 
2. Go to Card 4 of the Scripting Stack. 


Your first animation effect will take place entirely on this card. 


3. Choose the Oval tool from the Tools menu (or palette). 


The pointer changes to a crossbar. You'll use this tool to draw a circle on 
the card. First, you'll need to set the line width for the circle and set the 
Draw Centered option. 

4. Choose Line Size from the Options menu. 


A small box appears with line width choices. 
The Oval tool 


5. Click the second width from the left. 


The Line Size box closes automatically when you make the selection. 
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6. Choose Draw Centered from the Options menu. 


This option causes the circle to be drawn from the starting point 
outward when you drag, which makes it easy to center the circle on 
the card. 


7. Position the crossbar pointer near the card’s center, hold down 
the Shift key, and drag until the circle is about three inches in 
diameter. 


Holding down the Shift key makes a perfect circle. 


8. Release the mouse button when the circle is the right size. 
(Release the Shift key also.) 


If you're not satisfied with your first attempt, you can press Command- 
Z to undo it and try again. 


Make sure that the circle doesn’t overlap or crowd any other pictures or 
decorations that you may have drawn on the card with the Paint tools. Use 
the Eraser to remove any graphics that come too close. 


Drawing a smaller circle inside the first one 


Next, you'll make a smaller circle inside the large one and then position it near 
the large circle’s edge. 


1. Position the crossbar pointer inside the large circle, hold down 
the Shift key, and drag until the new circle is anywhere from 
three-quarters to an inch in diameter. 


Release the mouse button and Shift key when the circle looks right. Don’t 
click anywhere else when you're finished drawing it; go right on to the 
next step. 
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Operator precedence 


Order 


| oo 


SSE DN ER WO 


Operators 


x / div mod 
+ — 

& && 

> < <= >= € 2 
is in contains 
is not in 

= is is not <> 


Type of operator 


Grouping 

Minus sign for numbers 

Logical negation for Boolean values 
Exponentiation for numbers 
Multiplication and division for numbers 
Addition and subtraction for numbers 
Concatenation of text 

Comparison for numbers or text 
Comparison for text 

Comparison for text 

Comparison for numbers or text 
Logical for Boolean values 

Logical for Boolean values 


The Bucket tool 


Filling in the smaller circle 
Now you'll fill the smaller circle with a pattern. 
1. Choose the Bucket from the Tools menu or palette. 


2. Choose a pattern from the Patterns menu. 
If you haven’t chosen a pattern since you started up HyperCard, plain 
black will be selected. 

3. Click inside the smaller circle. 
The small circle should fill with the pattern you chose. 


< Everything changed? If the paint “leaked out” and filled other areas 
besides the small circle, just press Command-Z to undo the paint job. Then 
you'll have to use the FatBits option to inspect the small circle for “holes” 
where the paint could leak through. Close any gaps using the Pencil, and 
then try using the Bucket again. See the HyperCard User's Guide for 
details on using the Paint tools. 


The finished graphic should look approximately like that in Figure 5-2. 


m Figure 5-2 The finished graphic image 
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Write a handler to 
use tools and 
menu commands 
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To cause this graphic to rotate, you could select it and choose Rotate Left or 
Rotate Right from the Paint menu. However, that action would rotate the 
image 90 degrees only once. To make it spin, you’d have to choose a Rotate 
command repeatedly. You can have HyperCard perform this action with a 
HyperTalk handler. 


You can select the image from a handler by using the choose command 
to choose the Selection tool and then the drag command to drag across 
the image. But first, you need to know the starting point and ending point 
for dragging. 


Finding the starting point 


If you were going to drag across the image to select it, you would probably 
begin by positioning the pointer above and to the left of the image. That 
point would be your starting point. 


1. Press Command-M to see the Message box. 


2. Choose the Button tool. 
You'll make a button shortly; changing to the tool now just allows you 
to use the arrow pointer, which is easier to position, for the next step. 

3. Position the pointer to the upper left of the graphic image, as 
you would if you were preparing to drag across it. 
Be sure that the pointer is higher than the top of the image and farther to 
the left than the left edge of the image. 

4. Letting go of the mouse and leaving the pointer where it is, type 
the mouseLoc into the Message box. 


You must include the word the. 


Pixel is short for picture element, 
which is the smallest dot that you can 
draw on the screen. 


5. Press Return. 


You should see two numbers in the Message box. The numbers represent the 
horizontal and vertical position of the pointer on the screen as measured from 
the top-left corner of the card window. The distances are measured in 
pixels; the value of the top-left corner of the screen is 0, 0. 


The mouseLoc isa HyperCard function that tells you the current 
position of the pointer. As you learned in the last chapter, you can type 
HyperCard functions into the Message box to get their values. 


6. Make a note of these two numbers; you'll need to put them into 
your animation handler. 


Finding the ending point 
You use similar steps to find the ending point for dragging: 


1. Position the pointer to the lower right of the graphic image. 


Make sure the pointer is lower and farther right than the image. If 
necessary, move the Message box out of the way temporarily (drag it by 
the bar across the top). 


2. Leaving the pointer where it is, type the mouseLoc into the 
Message box. 


Again, be sure to include the. 
3. Press Return. 


4, Make a note of the new numbers in the Message box. These 
numbers will also go into your handler. 


5. Close the Message box. 
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Making a button and completing the handler 
Next, create a button to hold the handler that will cause the animation: 


1. Create a new button and name it Spin 


Choose the usual settings in the Button Info box. 
2. Click the Script button in the Info box to go to the script editor. 


3. Type the following lines between the existing lines, substituting 
the numbers you made note of in the previous sections for the 
ones shown here: 


choose select tool 

drag from 125,73 to 361,281 with commandKey 
repeat for 16 times 

doMenu "rotate right" 

end repeat 

choose browse tool 


When you type the line beginning with drag, be sure to substitute the 
numbers you got using the mouseLoc inthe Message box. The 

first pair of numbers, the starting point for the drag, should follow the 
word from. The second pair of numbers, the ending point, should 
follow the word to. The phrase with commandKey has the same 
effect as dragging with the Selection tool while holding down the 
Command key: the selection is tightened to the perimeter of the image. 


DoMenu lets you choose any command from an available HyperCard 
menu. As with other names, it’s a good idea to put the command name 
inside quotation marks. 


4, Press Tab to format the handler. 


Here’s how the handler should look, except for the numbers used with 
the drag command, which should be your own numbers: 


on mouseUp 
choose select tool 
drag from 125,73 to 361,281 with commandKey 
repeat for 16 times 
doMenu "rotate right" 
end repeat 
choose browse tool 
end mouseUp 


If you have any extra blank lines, you can select them and delete them. 
HyperCard just skips blank lines, however, when the handler is read. 


5. Click OK. 


The script editor closes. 


Trying it out 


Switch to the Browse tool and click the Spin button. 


You should see the circle turn through four complete rotations; that’s 
because the repeat statement specifies 16 repetitions of the 90-degree 
Rotate Right command. If you had not specified a number, the image would 
just keep turning “forever.” 


In the Clip Art stack that came with HyperCard you'll find a picture of an old 
car with a button labeled “Drive the car.” When you click the button, the car 
rolls forward and back. The script for that button contains a handler that 
selects the image and drags it back and forth, finally putting it back where it 
started. It’s another example of animation using the Paint tools in a handler. 
Feel free to look at the button’s script on your own. 
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Repeat isa keyword that tells HyperCard to perform a command or series 
of commands over and over again. Like if structures, repeat 

structures come in several varieties; the first line of a repeat structure 
can have any of these general forms: 


repeat [forever] 

repeat [for] number [times] 

repeat until condition 

repeat while condition 

repeat with variable = startValue to _finishValue 


You follow any of these first lines with a statement or list of statements 
making up the commands you want to have repeated. At the end, you must 
include end repeat to indicate the end of the list. 


Repeat structures cause HyperCard to go around in a “loop,” repeating 
steps until a particular endpoint occurs. Being able to use repeat structures 
saves you from having to retype or duplicate command lines over and over 
again. For example, without the repeat structure in the animation 
handler, you would have had to retype or copy and paste the line domenu 
"rotate right" 16 times to create the same effect. 


The version repeat [for] number [times] lets you specify how 
many times HyperCard will repeat the commands; you replace number with 
the number of repetitions you want. You used this version in the animation. 


The prepositions until and while specify different ways of looking 
at a situation. The condition is some state that has the value true or 
CALS. 


The repeat with form causes repetition to continue until the value of 
a variable changes from a starting value to an ending value. For example, 


repeat with count = 1 to 100 -- "count" is the variable. 
doMenu "rotate right" 
end repeat 


HyperCard adds 1 to the value of count after each rotation. This 
structure in the handler would cause the image to rotate 90 degrees 100 times, 
for 25 complete rotations. 


Set up the cards 


The Selection tool 


Animation using several cards 


Instead of changing the image on a single card, this next technique involves 
putting different images on sequential cards and then showing the cards 
rapidly. 


You'll use the same image in this version of animation. To get set up, you'll 
copy, paste, and turn the image on each of four cards. 


Copying and pasting the image once 

Follow these steps: 

1. Go to Card 4, if you aren’t there already. 

2. Choose the Selection tool from the Tools menu or palette. 
3. Drag to select the image on Card 4. 


4, Press Command-S to tighten the selection 
This step makes sure that you copy only the image you want, and not 
anything outside it. 


. Press Command-C to copy the image. 


6. Press the Right Arrow key to go to Card 5. 


You can also press Command-3 or switch to the Browse tool and click the 
right-arrow button. 


©, 
“~~ 


By the way: If pressing the Right Arrow key doesn’t work, try Option- 
Right Arrow. (You might have Text Arrows selected on the User 
Preferences card.) 


7. When Card 5 is on the screen, press Command-V to paste the 
image. 


Card 5 will be the first card of the four cards needed for this type of 
animation. 
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Adding more cards 


You have only one more card in the stack at this point, and you need three 
more to use for animation: 


= Press Command-N two times. 


You should see “This is Card 6” appear in the label field the first time you 
press the keys, and “This is Card 7” the second time. HyperCard inserts each 
new card immediately after the card you were on; you end up looking at 
Card 7. The card that was the old Card 6 has been renumbered to become 
Card 8. Figure 5-3 illustrates the addition of new cards. 


m Figure 5-3 New cards inserted after the current card 


This new card becomes 
the new number 6 


This new card becomes 
number 7 


This card’s number 
changes from 6 to 8 


This card’s number 
does not change 


Sequence before Sequence after 
inserting cards inserting cards 


Write a handler to show 


the cards 


Copying and pasting the image twice more 


Put rotated copies of the graphic image onto the remaining cards following 
these steps: 


1. Press the Left Arrow key to go back to Card 6. 


You can also press Command-2 or click the left-arrow button. 


2. Press Command-V to paste the image on Card 6. 


The graphic image should still be on the Clipboard. If nothing happens, go 
back to Card 5, reselect the image, and use Command-C to copy it. Then 
paste it on Card 6. 


3. With the image still selected, choose Rotate Right from the Paint 
menu. 


Each image needs to be rotated 90 degrees from the previous one to 
create the animation effect. 


4, Press Command-C to copy the rotated image. 
5. Go to Card 7 and press Command-V to paste the image. 
6. Choose Rotate Right from the Paint menu again. 


7. Repeat steps 4, 5, and 6, but this time going to Card 8, to paste 
and rotate the image for the last time. 


When you're finished putting the images on the cards, go back to Card 5, 
where you'll create a button and write a handler to perform the animation. 


The handler for the animation will again go into a button script. 


1. Create a new button and name it Spin 2 


Select the usual settings. 


2. Click Script to see the script editor. 


Animation using several cards 103 


104 


Chapter 5: Animation 


3. Type these lines between the existing ones: 


repeat for 10 
Go: Co card «5 
show 3 cards 
end repeat 

go. to: card: 5 


4. Press Tab to check the formatting of the handler. 
Here’s how the complete handler should look: 


on mouseUp 
repeat for 10 
go to card 5 
Show 3 cards 
end repeat 
go to card 5 
end mouseUp 


5. Click OK. 


6. Try the button. 


Choose the Browse tool and click the Spin 2 button. The image spins ten 
times and then stops. You'll see the numbers in the card identification field 
change and the Spin 2 button flash by each time you get to Card 5 (you'll fix 
this shortly). When the handler is finished, you should be on Card 5. 


Notice that the animation is faster going card-to-card than it was on a single 
card. That’s because in the first case HyperCard must redraw the image each 
time through the repeat structure, which takes some time. 


Here’s a commented version of the handler explaining what each line does: 


on mouseUp 


repeat for 10 -- The number of times to repeat. 
go to card 5 -- Always start here. 
show 3 cards -- Shows cards 6, 7, and 8. 


end repeat 
go-to: Card’ -5 -- Back to the starting card. 
end mouseUp 


Another way to control 


the spin 


You can add a “contingency plan” to your repeat structure that will give 
you another way to stop the image from spinning. 


1. Command-Option-click the Spin 2 button to see its script. 
You could also switch to the Button tool and Shift-double-click. 


2. Click before the word go at the beginning of the third line of 
the handler to place the insertion point in front of go to 
card 5. 


That’s the line just after repeat for 10. 


3. Type this line and press Return: 


if the mouse is down then exit repeat 


4, Click OK. 


5. Try the Spin 2 button again, and this time press down the mouse 
button before the ten cycles have completed. 


(You may have to hold the mouse button down for a half second— 
HyperCard might not detect a fast click.) 


Now when you start the image spinning you can click anywhere to stop it 
before it spins ten times. 


The line you added is a variation of the if structure. An if structure 
that has only one condition and only one action can be typed as a single line in 
your handler and doesn’t require the end if line. 


Exit is another keyword. Exit repeat jumps to the end of the 
structure (that is, to end repeat), stopping the repetition. Any 
instructions between end repeat and end mouseUp are then 
carried out. 
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Every time Card 5 appears during the animation, you see the Spin 2 button 
flash by. The numbers also change in the label field. Both these visual 
interruptions detract from the animation. Use the hide and show 
commands to remove the button and field temporarily while the animation 
is running: 


Some finishing touches 


1. Command-Option-click the Spin 2 button to see the script editor. 


2. Click before repeat at the beginning of the second line. 


You want to add new statements before the repeat structure. 


3. Type these statements, pressing Return after each line: 


hide field 1 
hide me 


Me refers to the object containing the handler (the button itself) and 
field 1 is background field 1 (the label field). 


4, Click before end to place the insertion point at the beginning 
of the line end mouseUp. 


You want to add the following statements after the repeat 
structure. 


5. Type these statements, pressing Return after each line: 


show field 1 
show me 


The entire handler looks like this: 


on mouseUp 
hide field 1 
hide me 
repeat for 10 
if the mouse is down then exit repeat 
go £O Gard 5 
show 3 cards 
end repeat 
go to card 5 
show field 1 
show me 
end mouseUp 
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6. Click OK. 


7. Try the Spin 2 button. 


Click the Spin 2 button with the Browse tool. If there are no other graphics 
on cards 5 through 8, the effect should now be cleaner, showing only the 
turning symbol. 


What you’ve done in this chapter 


You've learned two ways to create animation: by using Paint tools and menu 
commands in a script, and by using the show cards command with a 
sequence of cards. You’ve experimented with the repeat structure, a 
way of performing a set of commands over and over again. You've also 
learned how to use the function the mouseLoc in the Message box to 
find the screen coordinates of the pointer. 


Commands 

choose Chooses a tool just as though it had been chosen 
from the Tools menu using the mouse. 

doMenu Performs a menu command just as though you had 
chosen it from the menu with the mouse. 

drag Does the same thing as dragging using the mouse. 

show cards Shows cards one after another on the screen. The 
cards to be shown (all or some number) must be in 
sequence. 
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Keywords 
end repeat 
exit repeat 


repeat 


Functions 


the mouse 


the mouseLoc 


Miscellaneous 
commandKey 


from 


CO 


The last statement of a repeat structure. 
An alternative way out ofa repeat. structure. 


Begins the repeat structure. 


Has asa value either up or down, corresponding 
to the state of the mouse button. 


Gives the location of the pointer on the screen in 
horizontal and vertical coordinates. 


The HyperTalk name for the Command key. 


A preposition; used with the drag command and 
some other commands. 


A preposition; it’s required with the drag 
command and in one version ofa repeat 
structure, but it’s optional with the go command 
(as seen in Chapter 1). 


Choose 


DoMenu 


Syntax summaries 


This section contains syntax descriptions of the commands you used in this 
chapter. Use this section for reference as needed. 


The general structure of the choose command is as follows: 
choose toolName tool 


ToolName is any one of the HyperCard tools from the Tools menu. You must 
always use tool after the name. Here are the HyperTalk names for the 
tools that you can use: 


browse field reg[ular] poly[gon] 
brush lasso round rect [angle] 
bucket line select 

button oval spray 

curve pencil text 

eraser rect [angle] 


The only tool you can’t use from inside a handler is the Polygon tool. 


You can use the choose command only when the user level is set to 
Painting, Authoring, or Scripting. You can set and reset the userLevel 
property inside a handler with the set command, if you don’t want to 
change the user level permanently in a stack. 


The doMenu command’s structure is simple: 
doMenu "menultem" 


Menultem can be the name of a desk accessory in the Apple menu or the 
name of a menu command. It’s best to include the quotation marks around a 
name to indicate it’s a command name and not the name of a variable. 


“> By the way: Include three typed periods if that’s how a particular 
command is shown in the menu; for instance, "card info...". 
You must type the three periods; don’t use the ellipsis character (Option- 
semicolon). 
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Drag The drag command’s syntax is 
drag from start to finish [with key[, key2[, key3]]] 
Start and finish are the points on the screen where the command starts to 
drag and where it ends up. The points are expressed as coordinates: two 
numbers representing horizontal and vertical placement in pixels, separated 
by commas. As mentioned earlier, the top left corner of the card window 
is 0,0. 


You can determine the coordinates of the pointer’s position using the 
function the mouseLoc. 


Key, key2, and key3 are one or more of the following HyperTalk key names, 
which come after with and must be separated by commas: shiftKey, 
optionKey, or commandKey. Including more than one key has the 
same effect as holding down more than one key while dragging. 


Here are the general forms of show cards: 
Show Cards 


show [all] cards 
show number cards 


Number is the number of cards you want to show if you don’t want to 
show all of them. The cards are shown in sequence. 
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C H A P T E R 6 


Stacks You Can Build 


HIS CHAPTER DESCRIBES TWO STACKS YOU COULD BUILD AND SCRIPT ON YOUR 


own, starting with materials already available in HyperCard. 


This chapter is different from the preceding chapters in that you don’t have 
to build these hypothetical stacks as you go, although you can if you like. 
Trying to build the stacks may help you assimilate what you've learned so 
far. The development of the stacks is discussed in a general way, however, 


rather than detailed step by step. 
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If the example stacks in this chapter don’t appeal to you, you are free to 
experiment. Browse through the Idea Stacks folder for possibilities. For 
example, each card in the Stack Ideas stack comes with prewritten handlers in 
its background script. You can create new stacks from each of these “seed” 
cards by using the New Stack command and copying the background (the 
handlers are copied automatically). You could then add to and modify the 
scripts (and, for that matter, the appearance of the stack) to suit yourself. 


“> By the way: The HyperCard Stack Design Guidelines, available through 
Addison-Wesley Publishing Company, describes graphic, text, and 
instructional design principles as they apply to stacks. 


A travel records stack 


Suppose you wanted to computerize your records of vacation travels or 
business trips so that you could update them easily. You could create a stack 
in which to keep the information. 


For the first card of this stack you could use a map of your country or a 
world map. A transparent button placed over each state or country would go 
to a card specific for that state or country when you clicked it. From each of 
the state- or country-specific cards, you could have other buttons to take 
you to cards for the cities or other localities you’ve visited. Finally, the city 
cards would have fields to contain information on accommodations and 
restaurants, clients visited (for a business stack), or points of interest (for a 
vacation travel stack). 


Each time you visit a new state, you add a new transparent button to the 
country map and link it to a new card that you create for the state. Each 

time you visit a new city or other location, you add a new button for the city 
on that city’s state card, create a new city card, and fill in the information 

in fields. 
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Creating the stack 


To build such a stack, you would use three backgrounds: one for the country 
or world map, one for the states or provinces, and one for the cities or 
locations. The different backgrounds would allow you to have different 
common fields for each of the three geographic levels. The next sections 
describe how to create this stack. 


If you want to try to create this stack, go right ahead; but be aware that not 
all steps are written out. 


The first thing you need is a map of some sort as a starting point. The Card 
Ideas stack contains some maps of the United States; you can get to Card 
Ideas from the Home Card. The first card of Card Ideas is shown in Figure 6-1. 


m Figure 6-1 First card of the Card Ideas stack 
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Click one of the small U.S. maps to go to a card with the same map on it; the 
one labeled “US State map,” with state abbreviations, is a reasonable choice 
(Figure 6-2). 


= Figure 6-2 A U.S. map showing state abbreviations 


Check to see what elements of this card are background elements by pressing 
Command-B. Everything is in the background on this card, which means that 
if you copy the background you'll get everything you see. 


To create a stack with this card as your first card, choose New Stack from 
the File menu. In the resulting dialog box, keep “Copy current background” 
checked and give the stack a new name—something like “My Travel Stack.” 


Once you click New, you'll be in the new stack, even though the card on the 
screen won't have changed. You can then name this first background by 
choosing Bkgnd Info from the Objects menu and typing a name—for 
instance, “Map Background.” 


“ Stack building tip: It’s a good idea to name backgrounds because you 
might want to create different backgrounds that look very similar. You 
can confirm which one is which in that case by checking their names. 
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You can also name this first card in the Card Info box; for example, “Main 
Map.” You can then use the card’s name in any handlers you write. 


As with your practice stack, you can add a Home button to the background 
of this first card. You can copy a Home button, complete with script, from 
the Button Ideas stack or from any stack with a working Home button. 

Make sure you are working in the background before you paste the button. 


You could also add a title to the first card (either as regular text in a field or 
as Paint text). It’s also a good idea to add a line or two of instructions on 
the card, in case anyone besides yourself uses the stack; for example, “Click 
any state.” 


Because this stack uses buttons for each individual state or city to take you 
to the card you want, it’s probably not necessary to add arrow buttons for 
traveling. Rather than moving card-by-card, you'll want to jump around. 
While setting up the stack, you can use the arrow keys or the Go menu to 
move to different cards, or you can create temporary travel buttons that you 
can delete later. 


The next information level would be the state level. To create a new, blank 
background for the state cards in this same stack, simply choose New 
Background from the Objects menu. HyperCard will create a new card with 
the new, blank background. This card is the second card in the stack. 


The second background 


You can give this background a name such as “States Background” using the 
Bkgnd Info box. 


On each of the state cards, you want a map of the state, its name, and 
perhaps some fields for relevant information. It’s a good idea to create a 
background field to hold the states’ names, because putting the name in a 
field lets you search for the name with the Find command. 


You can create other background fields for other information that you want 
to have on every card. Give each card the same name as the state it represents, 
both in the name field and in the Card Info box. Add some instructions in 
Paint text to the background, such as “Click any location.” (Paint text in the 
background will appear on every card.) 
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Finally, you can add a background button to take you to the Home card and 
one to take you back to the main map card. This latter button’s script needs a 
mouseUp handler with the statement go to card "main map" 
(or whatever name the card has). You could alsoadd visual effect 
iris close or some other visual effect before the go statement. 


Each state card can have as its card picture (not in the background) an image 
of the state. One quick way to make a rough state outline is to copy the 
small state image from the main map using the Lasso or Selection tool. (You 
must be in the background to copy a background picture.) You then go to 
the appropriate state card, paste the image, and stretch it to a larger size using 
Command-drag or Shift-Command-drag. You can refine the rough outline 
further if you want. Another way to add a state outline would be to find a 
clip-art stack with pictures or maps in it and copy them with the Import 
Paint command. 


Figure 6-3 shows a background layout and a finished state card. 


m Figure 6-3 One possible layout for state cards; the background, showing fields, 
on the left, entire card on the right 
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The third background 


The next information level would be the cities, towns, or localities level, for 
which you can create another background by choosing New Background 
again; you'll get another blank card. You can name this third background 
“Local Background.” 


Again, make background fields for information such as the locality name, 
accommodations information, client addresses, restaurants, and so on— 
whatever information you want. 


When filling in the information, if you find you have more information than 
will fit into a particular field, you could add a second card for the locality, 
including a card button or buttons to get to and from the second card. You 
could also use scrolling fields, which allow you to add as much text as you 
want, regardless of the size of the field on the screen. 


< Stack building tip: It’s best not to use scrolling fields as a way of putting 
an enormous amount of text into one card. If you expect to have a great 
deal of text to fit into a small amount of space, consider using several 
cards to hold the text rather than putting it into a scrolling field. 


Put the fields’ permanent labels in Paint text in the background above each 
field—or you could create separate fields for the labels. Remember that you 
can use the Find command to search for text in fields, but you can’t search 
for Paint text. 


Add a background button to go back to the main map; you can copy it (and 
its handler, automatically) from the state card. Also include a card button to 
take you back to the state card. (You wouldn’t want to put this button into 
the background, because the destination for the button’s handler would have 
to be different for different localities.) You could add visual effects to these 
buttons’ handlers also. 
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Figure 6-4 shows a background layout for the locality cards and a finished 
example for a fictional city. 


= Figure 6-4 A possible layout for locality cards; the background, showing fields, 
on the left, entire card on the right. 


How the stack would work Here’s a summary of how you would use this stack: 


1. For each state you visit, create a transparent card button over the image 
of the state on the main map. For some states, the button may be 
difficult to size correctly because of the state’s shape. Try to center the 
button over the state abbreviation. 


On the eastern seaboard, where many small states are close together, you 
might want to have a transparent button over the whole area on the 
main map and create a second map card with a blank background for just 
that area. You could copy and paste the eastern states, and then enlarge 
the area by selecting and stretching it on the second map card. Copy the 
Home button also, and make a button to take you back to the main 
map card. 
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“. Important Always think twice before you erase or change any graphics in the 
background. Any change you make in the background will happen on every 
card sharing the background. 


You can cover background graphics on a card by using the Bucket or the 
Brush with a pattern or by using the Command key with the Eraser to 
“erase” with white (opaque) on the card layer. “. 


2. Create a new card using the second background for each state. Name the 
card the same as the state name. Then write a handler to link the 
transparent button on the main map to the respective card using the go 
command. The zoom open visual effect works well here. 


3, Add cities or locations (such as national parks) to each state’s map after 
you've visited them. Create a transparent button over each location. 


4. For each location you visit, add a new card using the third background. 
Name the card the same as the location. Link the button on the state card 
to the location card. 


5. Fill in the information for each place you visit in the appropriate fields. 


6. When you plan to visit a locality again, or when you want information for 
some other purpose, use your stack to get the information quickly. You 
can print each locality card if you need to. 


You could also include a mouseUp handler at the background or card level 
of the main map that would use the answer command to put up an alert 
box when someone clicks a state that doesn’t yet have a button. Use a 
message such as “That state hasn’t been visited yet.” An OK button will 
appear automatically with the message—or you can add any button label 
you like. 
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Creating the stack 


A flash card stack 


Flash cards are useful study aids for questions and answers, for vocabulary 
drill, or for any fact-memorization task. A word or a question is put on one 
side of a card, and the answer on the other side. You try to match each 
answer as you go through the cards. 


A stack that acted like a set of flash cards could have the answers contained 
in a hidden field, which would be shown when you type the correct answer 
into another field and click a button, or when you give up and ask for the 
answer by clicking another button. 


A flash card stack would most likely need only a single background. You 
might want to have the option of moving sequentially through all cards, 
picking a card at random, or sorting cards into a new random order (like 
shuffling). You would probably want to be able to tell where you are in the 
stack by seeing the number of the current card as well as the total number 
of cards. 


You can start by going to the Stack Ideas stack to look for some possible 
starting points for building your stack. You can get to Stack Ideas from the 
Home card. Figure 6-5 shows the first card of Stack Ideas. 


m Figure 6-5 First card of the Stack Ideas stack 
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Clicking any of the images takes you to a full-size card. These cards contain 
prewritten handlers for navigation buttons as well as other ready-made 
scripts, often in their backgrounds. The card that looks like a hand holding a 
note card might be a good choice for the flash card stack (Figure 6-6). 


= Figure 6-6 A card with a note card image on it 


You can check the background by pressing Command-B; you might also 
want to look at the fields on the card; you'll see there’s one large transparent 
field in the background. You can change the size of this field and duplicate it 
to make more fields if you want. 


To create a new stack from this card, choose New Stack from the File menu., 
copy the current background, and name the stack. 
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Features of the stack 
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The idea of this flash card stack is that the words or information on the cards 


changes, but the shape and appearance of the cards don’t. You can put 


essentially all the fields, buttons, and labels into the background. The test 
words and answers are typed into background fields; every card can have 
different text. 


Here is a description of the features needed to make a flash card stack for 
Spanish-to-English vocabulary: 


1. 
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For each card you go to, you should be able to see the number of the card 
and the total number of cards in the stack. You could make a field for 
each number and write a handler to put the correct numbers into the 
fields automatically. 


The Spanish word for which you are being tested needs to be in a field. 
A background field would be best. 


The insertion point should be placed automatically into another, blank 
background field where you would type your answer. 


The correct answer, in a third background field, should be hidden when 
you go to a new card. 


A button should be available to check whether the English word you type 
is correct. 


A button should be available for “giving up” and showing the hidden 
field. 


Something should happen if the guess is wrong—a message and a chance 
to try again. 


It would be nice to be able to choose random cards and to sort the cards 
in random order. 


Figure 6-7 shows a completed version of this stack, a vocabulary stack for 
Spanish. The card on the left shows the background, including fields. The card 
on the right shows the entire image, complete with a word, an answer, and 
the correct answer showing. 


= Figure 6-7 One possible layout for a flash card stack; the background, showing 
fields, on the left, entire card on the right 


Notice that the preexisting arrow buttons and Home button have been 
moved and changed to rectangle buttons. You can move any button 
anywhere you want it and change its style as you like; the button will still act 
the same way. 


The single field on the original card in Stack Ideas has been duplicated to 
create a total of six fields, all in the background: one field, at the top, holds 
the title of the stack; another contains the word in Spanish; a third field holds 
the correct answer, which is hidden until you get the right answer or give up; 
the next field is where you type your answer or guess; and the last fields are 
the small fields in the upper-right corner of the card that tell you the card 
number and the total number of cards. 
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The scripts 


This section shows the handlers that accomplish the flash card stack’s 
actions. Notice that the handlers have been placed where they work most 
effectively. 


Some objects have empty scripts—that is, their scripts contain no handlers— 
and so they are not listed here. The card scripts are empty and so are the 
scripts for all fields. 


The stack script 


The following handlers are placed at the stack level so that they are available 
to every card in the stack automatically. 


This first handler came with the stack; when the stack opens, the handler 
puts away the Message box in case it’s been left open: 


on openStack 
hide message box 
end openStack 


This next handler does three things; it uses the put command to put the 
number of each card and total number of cards, respectively, into the fields in 
the upper-right corner of the card, and it uses the click command to set 
the insertion point into the field where you type your answer, so you're ready 
to type immediately when the card opens. (The fields were given names in 
their Info boxes when they were made.) 


on openCard 
put the number of this card into field "cardNumber" 
put the number of last card into field "totalNumber" 
click at the loc of field "guess" 

end openCard 
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The 
return-arrow 
button 


The final handler hides the field with the correct answer and blanks out the 
Guess field and the Card Number field: 


on closeCard 

hide field "answer" 

put empty into field "guess" 

put empty into field "cardNumber" 
end closeCard 


It’s better to hide the Answer field and to blank out the Guess field when 
leaving a card (closeCard). If you hid the Answer field upon opening the 
card (openCard), you would see a “ghost” of the answer when the new 
card appeared, spoiling the test. Blanking out the Card Number field when 
leaving the card is also cleaner; otherwise, if the card number had changed, 
you would see a “ghost” of the old number. 


The background script 


The background script contains this handler, which came with the stack: 


on openBackground 
push recent card 
end openBackground 


The openBackground handler contains the statement push 
recent card. The “recent card” is whatever card you were on just 
before you came to this stack, if any. This statement keeps track of that card 
by “pushing” it onto a memory stack (different from a HyperCard stack). 
The return-arrow button in the lower-right corner of the card contains the 
reverse command, pop card. When you click the return-arrow button, 
the card that had been pushed is now “popped” out of the memory stack, 
and you go back to it. You use the push and pop card commands to 
have HyperCard keep track of where you’ve been so you can get back 
automatically. 


This handler could just as easily have been at the stack level. In a stack with 
multiple backgrounds, it probably ought to be at the stack level. 
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The button scripts 


The scripts for the Home button and the right-arrow and left-arrow buttons 
are what you would expect them to be from writing the handlers in the 
earlier chapters. 


The return-arrow button script contains this handler, as mentioned in the 
preceding section: 


on mouseUp 
pop card 
end mouseUp 


The “Check answer” button script contains this handler: 


on mouseUp 
if field "guess" is in field "answer" then 
show field "answer" 
else 
beep 
answer "Oops. Select the word and try again." 
end if 


end mouseUp 


The if statement uses the phrase is in to compare the string of 
characters typed into the Guess field with any string of characters in the 
Answer field, allowing you to include several meanings for any word. In the 
sample shown previously in Figure 6-7, either house or home would be a 
correct answer. Capitalization doesn’t matter. 


The “Show answer” button has this handler: 


on mouseUp 
show field "answer" 
end mouseUp 


The “Random Card” button has this handler: 


on mouseUp 
visual effect scroll down 
go to any card 

end mouseUp 
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How the stack would work 


The “Shuffle” button script contains this handler: 


on mouseUp 
sort numeric by random(the number of cards) 
end mouseUp 


The sort command puts all the cards in a stack in order, or in this case in 
no particular order. This command can sort in ascending or descending order, 
alphabetically (text) or numerically, and you can sort by such things as card 
name, card number, a field name, a word in a field, and so on. Here are some 
examples: 


sort ascending text by last word of field "Name" 
sort descending numeric by field 2 


In the example stack, the random() function causes a sort into random 
order. The parentheses must contain a number—in this case, it’s the number 
of cards in the stack. You could use the random() function to pick a 
number from 1 to 10 by putting 10 inside the parentheses—for instance, as 
part of a game. 


Once the stack is set up, its use is simple. 


1. Adda new card for every new word. 
2. Type the word into field 1 (which is named Word). 


3, Use the show command in the Message box to show the hidden 
Answer field and then type the correct answer or answers into the field. 


4. For review purposes, use the buttons to go through the stack and to 
shuffle its order. Type your answer for each word into the Guess field 
and click “Check answer.” If you can’t make a guess, click “Show answer.’ 


? 


< By the way: You can sort the cards into alphabetical order from the 
Message box with the statement 


sort ascending text by field "word" 


You could copy and modify the stack for other languages or subjects. You 
could even reverse the action of the stack—that is, make it English-to- 
Spanish rather than Spanish-to-English—simply by changing the handlers. 
(Can you think of how you might do this?) 
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Where to go from here 


Now that you’re an experienced scripter, you can go on to other sources to 
learn more about HyperTalk and the possibilities of using HyperCard. Many 
people have written books on HyperCard and scripting that you might find 
helpful. The HyperCard Script Language Guide contains complete 
descriptions of HyperTalk elements. The HyperCard Help system is also a 
good reference to consult while you're working. 


Some of your most valuable scripting information is likely to come from your 
own experimentation and experience. Think of ways you can change existing 
stacks to suit yourself—and then look at those stacks’ scripts to see how 
they work and how you might modify them. Use your practice stack as a 
place to test handlers and as a repository for buttons with prewritten 
handlers and other scripts that you can copy and paste when you want them. 
Talk to other HyperCard users and scripters, and exchange tips and shortcuts. 
Most of all, enjoy using a new tool that enhances your creativity. 
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A ? P E N D Nt X 


HyperTalk Summary 


HIS APPENDIX CONTAINS SYNTAX STATEMENTS FOR ALL HYPERTALK BUILT-IN COMMANDS 
and functions; lists of keywords, properties, constants, and system messages; a table of 
operators and their order of precedence; keyboard shortcuts for seeing scripts; and synonyms 


and abbreviations. 


The Quick Reference Card contains the script editor commands, keyboard shortcuts, 


commands and functions, and list of operators. 
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Syntax statement notation 


Syntax statements show the most general form of a command or function, with all elements in 
the correct order. The syntax statements in this book use the following typographic 
conventions: Words or phrases in this kind of type are Hypertalk language elements 
that you type literally, exactly as shown. Square brackets [] enclose optional elements that may 
be included if you need them. (Don’t type the square brackets.) In some cases, optional 
elements change what the command does; in other cases they have no effect except to make 
the command more readable. Words in italic are placeholders describing general elements, not 
specific names; you must replace them in an actual command. For example, effectName stands 
for any of the HyperTalk visual effectnames: barn door, checkerboard, zoom, 

and so on. 


It doesn’t matter whether you use uppercase or lowercase letters in HyperTalk, but names that 
are formed from two words are shown in small letters with a capital in the middle 
(1ikeThis) merely to make them more readable. 


The HyperTalk prepositions of and in are interchangeable—the syntax statements use the 
one that sounds more natural. 


Commands 


The following list includes all HyperTalk commands available in version 1.2.2. A full description 
of the action of these commands is beyond the scope of this appendix. The HyperCard Help 
system contains a HyperTalk reference section explaining the use of the commands through 
version 1.1. The HyperCard Script Language Guide also contains complete descriptions of 
HyperTalk commands, functions, and so on. Many other books on HyperCard and scripting are 
also available. 

add expression to destination 

answer "question" [with "reply" [or "reply2" [or "reply3"]]] 

arrowKey keyName 

ask [password] question [with defaultAnswer] 

beep number 

choose toolName tool 

click at location [with key[, key2[, key3] ] ] 

close file fileName 
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close printing 

controlKey asciiNumber 

convert container to format [and format] 

delete chunk [of container] 

dial expression [with modem [modemCommands] ] 
divide destination by expression 

doMenu menultem 

drag from start to finish [with key[, key2[, key3] ]] 
edit script of object 

enterKey 

find [chars] expression [in field fieldDesignator] 
find [word] expression [in field fieldDesignator] 
find string expression [in field fieldDesignator] 
find whole expression [in field fieldDesignator] 
functionkey keyNumber 

get expression 

go [to] [stack] "stackName" 

go [to] bkgndDescriptor [of [stack] "stackName" ] 
go [to] cardDescriptor [of bkgndDescriptor) [of [stack] "stackName" ] 
help 

hide menuBar 

hide windowName 

hide object 

hide picture 

lock screen 

multiply destination by expression 

open [document with] application 

open file fileName 

open printing [with dialog] 

play "voice" [tempo tempoValue} [" notes" ] 

play stop 

pop card [preposition destination] 

print card 

print expression cards 


print cardDescriptor 
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print document with application 

push cardDescriptor 

put expression [preposition destination] 

read from file fileName until character 
read from file fileName for numberOfCharacters 
reset paint 

returnKey 

select object 

select [preposition] expressionof field 
select [preposition] expression of msg 
select [preposition] text of field 
select empty 

set [the] property [of object] to value 
show [all] cards 

show number cards 

show menuBar 

show windowName [at h, v] 

show object [at h, v] 

show Picture 

sort [direction] [style] by expression 
subtract expression from destination 
tabKey 

type expression [with key[, Rey2[, Rey3] ] ] 
unlock screen [with effectName] 
visual [effect] effectName [speed] [to image] 
wait [for] number [seconds] 

wait until condition 

wait while condition 

write source to file fileName 
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Functions 


The following list includes all HyperTalk functions available in version 1.2.2. 


When using functions in HyperTalk statements you must either use the word the before the function name or 
add parentheses after it (both forms are shown in the list that follows). The parentheses are used to enclose any 
values on which the function operates. These values are called parameters. If the function takes several parameters 
(for example, the average function), the parameters must be separated by commas. See the HyperCard Script 
Language Guide for a more complete discussion of functions and parameters. 


Factoris a single value, such as the number 5 or a container holding a value; expression can be a single factor or a 
combination of several factors and operators that results ina value, suchas (2+3) or (2+(field 1)). 


The result or use of a function is shown on the right side of the page. 


the abs of factor Absolute value 

abs (expression) 

annuity (rate, periods) Calculates an annuity 

the atan of factor Arc tangent—radians 

atan (expression) 

average (list) Calculates an average 

the charToNum of factor Returns the ASCII value of a character 

charToNum ( expression) 

the clickH Gives horizontal coordinate of where the user last clicked 
the clickLoc Gives horizontal and vertical coordinates of where the user 
clickLoc () last clicked 

the clickv Gives vertical coordinate of where the user last clicked 
the commandKey Condition of the Command key: up or down 
commandKey () 

compound (rate, periods) Calculates compound interest 

the cos of factor Cosine—radians 

COS (expression) 

the [modifier] date Current date set in the Macintosh: long or short 

the diskSpace Amount of free space on the current disk 


diskSpace () 
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the exp of factor 
exp (expression) 


the expl of factor 
expl (expression) 


the exp2 of factor 
exp2 (expression) 


the foundText 
the foundChunk 
the foundLine 
the foundField 


the length of factor 
length ( expression) 


the ln of factor 
1n (expression) 


the lnl of factor 
Ini (expression) 


the log2 of factor 
log2 (expression) 


max (list) 
min (list) 


the mouse 
mouse () 


the mouseClick 
mouseClick () 


the mouseH 
mouseH () 


the mouseLoc 
mouseLoc () 


the mouseV 
mouseV () 


[the] number of objects 
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Mathematical exponential 
1 less than mathematical exponential: exp () -1 
The value of 2 raised to the power of factor 


Returns characters found by the find command 
Returns a description of where the text is found 
Tells which line the found text is in 

Tells which field the found text is in 


Number of characters in a text string 
Natural logarithm—base-e 

1 plus the natural logarithm: 1n (1+/factor) 
Base-2 logarithm 


Returns the highest number value of a list 
Returns the lowest number value of a list 


Condition of the mouse button: up or down 
Returns true _ if the mouse button is clicked 
Horizontal position of the pointer on the screen 
Horizontal and vertical coordinates of the pointer 


Vertical position of the pointer 


Number of buttons/fields on current card or background 


Number of characters, words, lines, and so on in 
text string 


[the] number of chunks in factor 


[the] number of cards of background Number of cards in specified background 


the numToChar of factor Returns the character corresponding to an ASCII value 


numToChar (expression) 


offset (string1, string2) 


the optionKey 
optionkey () 


the param of factor 
param (expression) 


the paramCount 
paramCount () 


the params 
params () 


the random of factor 
random (expression) 


the result 
result () 


the round of factor 
round (expression) 


the screenRect 
screenRect () 


the seconds 
seconds () 


the selectedText 
the selectedChunk 
the selectedLine 
the selectedField 


the shiftKey 
shiftKey () 


the sin of factor 
Sin (expression) 


Gives number of characters between the beginnings of 
two strings 


Condition of the Option key: up or down 

Returns the value of a parameter in a list 

The total number of parameters 

The entire list of parameters 

Gives a random integer from 1 to the value of factor 
Returns a text string if find or go is unsuccessful 


Rounds to nearest integer: an odd integer plus 0.5 
rounds up; an even integer, down 


The rectangle of the screen in which the menu bar 
is displayed: left, top, right, bottom coordinates 


Number of seconds between midnight January 1, 1904, and 
the current time in your Macintosh 


Returns the text currently selected 
Describes the location of the selected text 
Tells which line the selected text is in 
Tells which field the selected text is in 


Condition of the Shift key: up or down 


Sine—radians 


Functions 135 


the sin of factor 
Sin (expression) 


the sound 
sound () 


the sqrt of factor 
sqrt (expression) 


the tan of factor 
tan (expression) 


the target 
target () 


the ticks 
ticks () 


the [modifier] time 
time () 


the tool 
tool {) 


the trunc of factor 
trunc (expression) 


the value of factor 
value (expression) 


the [long] version [of HyperCard] 


version () 


the version of stackDescriptor 
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Sine—radians 
Name of sound resource currently playing, or "done" 


if none is playing 


Square root of a positive number—a negative number 
gives the result NAN (001) meaning “not a number” 
Tangent—radians 

Identifies the original recipient of a message 

Number of ticks (Yo second) since the Macintosh was 
turned on or restarted 

Gives time as a text string: long, short, abbreviated 
Name of currently chosen tool 

The integer part of a number in function 

Gives the value of a string as an expression 


Returns the version number of HyperCard 


Tells version of HyperCard used to create, compact, 
change since compacted, and make latest changes, plus 
the date modified in seconds since January 1, 1904 


Keywords 


The following list of HyperTalk keywords includes their syntax, where appropriate, or a 
comment on their use. Keywords are predefined; you can’t redefine them—for instance, you 
can’t use a keyword as a name of a variable. 


Send _ is the only keyword that can be used in the Message box. 


do do expression 
else -- used with "if" structures 
end end functionName 

end messageName 

end if 


end repeat 


exit exit functionName 
exit messageName 
exit repeat 
exit to HyperCard 


function function functionName [ parameterList] 
global global variableList 

if -- begins "if" structures 
next next repeat 

on on messageName 

pass pass functionName 


pass messageName 


repeat -- begins “repeat"™ structures 
return return expression 

send send "messageName [parameterlist]" [to object] 
then -- used in "if" structures 
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Properties 


This section lists properties of the HyperCard environment and of objects available in HyperCard 
version 1.2.2. 


Global properties 


blindTyping lockMessages textArrows 
cursor lockRecent userLevel 
dragSpeed lockScreen userModify 
edit Bkgnd numberFormat 

language powerkeys 


Window properties 


the bottom of loc[ation] the topLeft of 
the bottomRight of rect [angle] the width of 
the height of the right of 

the left of the top of 


Painting properties 


brush multiple textFont 
centered multiSpace textHeight 
filled pattern textSize 
grid polySides textStyle 
lineSize textAlign 


Stack properties 


cantDelete freesize script 
cantModify name size 
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Background properties 


cantDelete 
ID 


Card properties 


cantDelete 
ID 


Field properties 


autoTab 

the bottom of 

the bottomRight of 
the height of 

8, 

the left of 
loc[ation] 
lockText 

name 


Button properties 


autoHilite 

the bottom of 

the bottomRight of 
the height of 
hilite 

icon 

ID 

the left of 
locfation] 


name 
number 


name 
number 


number 

rect [angle] 
the: right. .of 
script 
scroll 
showLines 
style 
textAlign 
textFont 


name 
number 

rect [angle] 
the right of 
SCrEpL 
showName 
style 
textAlign 
textFont 


script 
showPict 


SCripPL 
showPict 


textHeight 
textSize 
textStyle 

the top of 

the topLeft of 
visible 
wideMargins 
the width of 


textHeight 
textSize 
textStyle 

the top of 

the topLeft of 
visible 

the width of 
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Constants 


Constants are named values that never change. You can’t use the name of a constant as a 


variable name. 


down 


empty 
false 
formFeed 
lineFeed 
pi 

quote 
return 
space 
tab 

Lrue 


up 


zero..ten 
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The value of the key functions for Command, Option, and Shift keys 
and for the mouse button when pressed 


The string containing nothing (the null string)—same as "" 
The opposite of true 

The form feed character, ASCII 12 

The line feed character, ASCII 10 

The value of pi to 20 decimal places 

The double quotation mark character 

The return character, ASCII 13 

The space character, ASCII 32—same as " " 

The horizontal tab character, ASCII 9 

The opposite of false 


The value of the key functions for Command, Option, and Shift keys 
and for the mouse button when not currently pressed 


The numbers 0) through 10 


System messages 


These messages are sent to the objects specified to inform them of system events. Some 
messages are accompanied by a variable (var), the nature of which depends on the message. For 
example, the arrowKey variablecanbe left, right, up, or down. 


Messages sent to a button 


deleteButton mouseLeave 
mouseDown mouseStillDown 
mouseEnter mouseUp 


Messages sent to a field 


closeField mouseLeave 
deleteField mouseStillDown 
enterInField mouseUp 
mouseDown mouseWithin 
mouseEnter newField 


Messages sent to the current card 


arrowKey var functionKkKey var 
closeBackground help 

closeCard hide var 
closeStack idle 
controlKey var mouseDown 
deleteBackground mouseStillDown 
deleteCard mouseUp 
deleteStack newBackground 
doMenu var newCard 
enterKey newStack 


mouseWithin 
newButton 


openField 
returniInField 
tabKey 


openBackground 
openCard 
openStack 

quit 

resume 
returnKkey 

show var 
startUp 
suspend 

tabKey 
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Operator precedence 


The table below shows the order of precedence of HyperTalk operators. The order of precedence 
determines which operation HyperCard performs first when evaluating an expression. Operators 
are evaluated from left to right, except for exponentiation, which is from right to left. 
Parentheses force evaluation in a certain order; forexample, 2*3+5 yields 11, but 

2* (3+5) yields 16. 


Order Operators Type of operator 
1 ( ) Grouping 
2 - Minus sign for numbers 
not Logical negation for Boolean values 
3 . Exponentiation for numbers 
4 x / div mod Multiplication and division for numbers 
5 ae Addition and subtraction for numbers 
6 & && Concatenation of text 
7 >< @—= b= Ee Comparison for numbers or text 
is in contains Comparison for text 
is not in Comparison for text 
8 = is is not <> # Comparison for numbers or text 
9 and Logical for Boolean values 
10 or Logical for Boolean values 
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Shortcuts for seeing scripts 


These shortcuts were introduced with HyperCard version 1.2. 


Key combination Effect 

Command-Option Display buttons; click a button with 
keys down to edit its script 

Shift-Command-Option Display fields and buttons; click a field (or 
button) with keys down to edit its script 

Command-Option-C Edit script of current card 

Command-Option-B Edit script of current background 

Command-Option-S Edit script of current stack 


Synonyms and abbreviations 


These synonyms and abbreviations include those introduced with HyperCard 
version 1.2. 


Term Synonym or abbreviation 
abbreviated abbr 
abbrev 
background bg 
bkgnd 
backgrounds bgs 
bkgnds 
button btn 
buttons btns 
card ed 
cards cds 
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Term Synonym or abbreviation 


character char 
characters chars 
commandKey cmdKey 
field fia 
fields fids 
gray grey 
location Loc 
message box message 
msg box 
msg 
middle mid 
picture PLce 
previous prev 
rectangle TSCE 
regular polygon reg poly 
round rectangle round rect 
second (time unit) sec of secs or seconds 
second (ordinal) sec or secs or seconds 
spray can spray 
ticks Eek 
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Glossary 


algorithm: A step-by-step procedure for solving a problem 
or accomplishing a task. Writing HyperTalk handlers or 
programs in other languages often begins with figuring out a 
suitable algorithm for a task. 


ASCII: Acronym for American Standard Code for 
Information Interchange, pronounced “ASK-ee.” A standard 
that assigns a unique number to each text character and 
control character. ASCII code is used for representing text 
inside a computer and for transmitting information between 
computers and other devices. 


background: A “holding area” where you can place 
elements that you want a group of cards to have in common. 
A background is an object and thus has a script; you can 
place handlers in its script that you want to be accessible to all 
cards in a group. See also object. 


background picture: The part of the screen image that is 
common to all cards sharing a background; that is, the part 
that’s not specific to a card. 


card picture: The part of the screen image that is specific to 
the card; that is, the part that’s not on the background level. 


command: A HyperTalk “action item.” Commands are 
instructions in HyperTalk for HyperCard to carry out. 
HyperCard has approximately 50 built-in commands. 
Compare with function, keyword. 


comments: Descriptive lines of text in a script or program that 
are not intended as instructions for the computer but rather 
as explanations for people to read. Comments are set off from 
instructions by symbols called delimiters, which vary from 
language to language. In HyperTalk, two hyphens (-—) 
indicate the beginning of a comment. 


constant: An entity having a fixed, unchanging value. 
HyperTalk contains a number of constants, such as true, 
false, up, down, and pi. Compare variable. 


container: A place where you can store a value; examples 
are HyperCard fields, the Message box, and variables. See 
also values. 


delimiter: A character used to mark the beginning or end of 
something, that is, to define limits. For example, double 
quotation marks act as delimiters for literals. Comments in 
HyperTalk are set off with two hyphens at the beginning of the 
comment and a return character at the end. 


empty: (adj.) Used to describe scripts that contain no 
handlers. Every HyperCard object has a script, even if the 
script is empty. See also null. 


ex-command or external command: See XCMD. 


function: A formula that HyperCard uses to obtain a value. 
You must sometimes supply a function with starting values or 
parameters. HyperCard has approximately 50 built-in 
functions. Compare with command, keyword. 


global variable: A variable that is valid for all handlers in 
which it is declared. You declare a global variable by 
preceding its name by the keyword global. Compare 
with local variable. See also variable. 


handler: A set of HyperTalk instructions specific to a 
message. A handler must begin with the keyword on and 
end with the keyword end. Both keywords must be 
followed by the name of the message. 


keyword: A HyperTalk word having a predefined meaning 
that you cannot change. Some examples of keywords are 
end, if, on, repeat, and send. 
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literal: (n.) Something you want taken literally. In HyperTalk 
you use quotation marks ("  ") to set off a string of 
characters as a literal, such as the name of an object or a 
group of words you want treated as a text string. 


local variable: A variable that is valid only within the handler 
in which it is used. Compare with global variable. See also 
variable. 


loop: A section of a handler that is repeated until a limit or 
condition is met, such asina repeat. structure. See 
loop. 


message: A string of characters sent to an object. You can 
write handlers in the object's script containing instructions for 
HyperCard to carry out when the message is received. 
Messages that come from the system—from events such as 
mouse clicks, keyboard actions, or menu commands—are 
called system messages. Messages can also be sent from the 
Message box or from handlers. See also handler, object 
hierarchy. 


message-passing hierarchy: See object hierarchy. 
metasymbol: See syntax. 


null: (adj.) Having no value at all, not even zero. The 
HyperTalk constant empty is defined as a string 
containing nothing, that is, a null string. A string containing 
zero wouldnotbe empty. 


object: Any HyperCard element that has a script associated 
with it and that can receive and send messages. Objects are 
stacks, backgrounds, cards, fields, and buttons. 


object hierarchy: The order in which a message is passed 
between objects. For example, a message that goes first to a 
button, such as mouseUp, would go next to the card, 
then the background, then the stack, and finally to HyperCard 
itself, unless intercepted and acted upon by a handler. 


operator: A character or group of characters that causes a 
particular calculation or comparison to occur. Operators 
operate on values. For example, the plus sign (+) is an 
arithmetic operator that adds numerical values. 


146 Glossary 


parameters: Values that accompany or are acted upon by a 
function. Parameters in HyperTalk are separated by commas. 


pixel: Short for picture element; the smallest dot you can 
draw on the screen. The position of the pointer is often 
represented by a set of two numbers separated by commas. 
These numbers are horizontal and vertical distances of the 
pointer from the top and left edges of the card window, 
measured in pixels. The top-left corner of the screen has the 
coordinates 0, 0. 


properties: Characteristics of objects or of HyperCard as a 
whole. For example, setting the user level to Scripting changes 
the userLevel property of HyperCard to the value 5. 
Properties are often selected as options in dialog boxes or on 
palettes, or they can be set from handlers. 


script: A collection of HyperTalk instructions associated with 
a HyperCard object. You use the object’s script editor to add 

to and revise its script. Every object has a script, even though 

some scripts are empty; that is, they contain nothing. See also 

handler, object. 


script editor: A large dialog box containing a window in 
which you can type and edit a script. The top line of the script 
editor box identifies the object to which the script belongs. 
You use keystroke commands to edit text in the script editor. 
See also handler, object, script. 


scripting: The act of writing scripts; writing programs in 
HyperTalk. Also Scripting, the User Level that allows you to 
look at and change objects’ scripts. 


string: A sequence of characters. You can compare and 
combine strings in different ways using operators. For 
example, in HyperTalk 23 + 23 will result in 46, but 
23 & 23 will result in 2323. 


syntax: A description of the way in which language elements 
fit together to form meaningful phrases. A syntax statement for 
a command shows the command in its most generalized 
form, including placeholders (sometimes called 
metasymbols) for elements you must fill in as well as optional 
elements. 


system message: See message. 


tick: One-sixtieth (%0) of a second. The wait command 
assumes a value in ticks unless you specify seconds by adding 
secs or seconds. 


values: Information on which HyperCard operates. Values in 
HyperCard are essentially strings of characters—they are not 
formally separated into types. For example, a numeral could 
be interpreted as a number or as text, depending on what 
you do with it in a handler. 


variable: An entity that has a changing value. HyperCard has 
built-in variables suchas it and the selection. You 
can create a variable to hold some value (either numbers or 
text) simply by using its name with the put command and 
putting the value into it. Compare with constant. See also 
container, global variable, local variable. 


XCMD: Short for external command, a command written in 
a computer language other than HyperTalk but made 
available to HyperCard to extend its built-in command set. 
Similarly, an XFCN, or external function, is a function written 
in another language. 
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Index 


& (ampersand) 21, 25 
& & (double ampersand) 21, 25, 44 
-- (double hyphen) 83 


A 


abbreviations and synonyms 143-144 
accidental notes 42 
after 0 
alert box (answer command) 69 
ampersand (&) 21, 25 
ampersands, double («&) 21, 25, 44 
animation 
repeat structures and 99-100 
show cards command and 110 
answer command 69 
arithmetic commands 88 


B 


background button, abbreviations 
for 81 
backgrounds 
changing 119 
defined 5 
fields in 74 
naming 114 
beep command 40 
before 


C 


card field, abbreviations for 81 
cards, new 102 

choose command 109 
color with visual effects 28 
commandKey 108, 110 
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commands 130-132 


answer 69 

arithmetic commands 88 
beep 40 

choose 109 

defined 86 

doMenu 109 

drag 110 

external commands 68 
flash 51,68 

get 80,89 

go 13, 23-24 

hide 70 


keyboard commands for seeing 


scripts 143 
naming commands 60 
play 41-43 
pop card 125 
push 125 
put 24,90 


script editor commands 35 


set 71 

show 71 

show cards 110 
sort 127 
visual 36, 38-39 
voice 41 

wait 72 


comments 83 
constants 85, 140 
containers 


defined 73 
fields as 74 

it 69, 80, 85 
Message box 84 


the selection 84 
variables 85 
coordinates of screen position 110 
creating new stacks 5 


D 


doMenu command 109 

dotted notes 42 

double ampersand (&&) 21, 25, 44 
double hyphen (--) 83 

drag command 110 

duration code 42 


E 


else 66, 68 

end 25 

end if 66, 68 

exit 105 

external commands 68 


F 


fields, background (as containers) 74 
flash command 51, 68 

from 109 

functions 86, 108, 133-136 


G 


get command 80, 89 
global variables 85 
go command 13 
defined 24 
syntax of 23 


H 


handlers 47 

hide command 70 
hilite 69 

hyphens, double (--) 83 


I 


identification line (in script editor) 12 


idle 47 

if structures 66-68 
image 38 

inserting new cards 102 
into 9 

it 69, 80, 85 


J,K 
keyboard commands 
for seeing scripts 143 
in script editor 35 
keywords 138 
else 66, 68 
end 25 
end if 66,68 
exit 105 
if 66, 68 
on 25 
send 70 
then 66, 68 


L 
local variables 85 


M 
Message box 84 
message handlers 47 
message-passing hierarchy 48-50, 
54-55 

messages 

interception of 58 

system messages 13, 24, 141 
modifiers 24 


mouse 108 


mouseLoc 108 
mouseUp 13, 24 
music. See play command 


N 

naming backgrounds 114 
naming commands 60 

new cards, inserting 102 

new stacks, creating 5 

next 24 

notes (play command) 42 
numberFormat 80 
numerals, interpretation of 74 


O 
object hierarchy 48-50, 54-55 
objects 27-28 
octave 42 
on 25 
openCard 24 
operators 
calculations and 88 
defined 84 
precedence of 142 
optional elements in syntax 39 
optionKey 110 
Option-Return 35, 43-44 


P 

parameters 133 

pitch range 42 

pixel, defined 97 

placeholders in syntax 39 

play command 41-43 
specifying notes 42-43 
syntax of 41 

pointer, position on screen 110 

pop cardcommand 125 

previous 24 

properties 69, 71, 138-139 

push command 125 

put command 24, 90 


Q 
quotation marks 23, 43-44 


R 
repeat structures 99-100 


S 
screen position 110 
script editor 12 

commands in 35 

long lines in 43-44 
scripts, defined 47-48 
selection & 
send keyword, syntax of 70 
set command 71 
shiftKey 110 


shortcuts. See keyboard commands 


show cards command 110 
show command 71 


“soft” return (Option-Return) 35, 43-44 


sort command 127 
sound effects 
beep command 40 
play command 41-43 
speaker volume 40 
speed 
with play command 41 
with visual effects 33 
stacks, creating 5 
strings 21 


synonyms and abbreviations 143-144 


syntax 39 

syntax statements 
answer command 69 
arithmetic commands 88 
choose command 109 
doMenu command 109 
drag command 110 
get command 89 
go command 23 
hide command 70 
notation of 130 
optional elements in 39 


Index 
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syntax statements (continued) 
placeholders in 39 
play command 41 
put command 90 
send keyword 70 
set command 71 
show cards command 110 
show command 71 
visual command 39 
wait command 72 

system messages 13, 24, 141. See also 

messages 


T 


tempo 41 

text in background fields 74 
the mouse 108 

the mouseLoc 108 

the selection &% 
then 66, 68 

ticks 72 

to 25, 108 

tool names 109 

triplet notes 42 
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U,V 


variables 85 
visual command 
effect names 36 
image 38 
syntax of 39 
visual effects 
color and 28 
image 38 
list of 36 
speed 33 
visual command syntax 39 
voice (play command) 41 


W 


wait command 72 
window names 70 


X, Y, Z 
XCMD 68 


LIMITED WARRANTY ON MEDIA AND REPLACEMENT 


If you discover physical defects in the manuals distributed with an Apple product or in the 
media on which a software product is distributed, Apple will replace the media or manuals 
at no charge to you, provided you return the item to be replaced with proof of purchase to 
Apple or an authorized Apple dealer during the 90-day period after you purchased the 
software. In addition, Apple will replace damaged software media and manuals for as long 
as the software product is included in Apple’s Media Exchange Program. While not an 
upgrade or update method, this program offers additional protection for up to two years or 
more from the date of your original purchase. See your authorized Apple dealer for 
program coverage and details. In some countries the replacement period may be different; 
check with your authorized Apple dealer. 


ALL IMPLIED WARRANTIES ON THE MEDIA AND MANUALS, INCLUDING IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, 
ARE LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE 
ORIGINAL RETAIL PURCHASE OF THIS PRODUCT. 


Even though Apple has tested the software and reviewed the documentation, APPLE MAKES 
NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH 
RESPECT TO SOFTWARE, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR 
FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS SOFTWARE IS SOLD “AS 
Is,” AND YOU THE PURCHASER ARE ASSUMING THE ENTIRE RISK AS TO ITS 
QUALITY AND PERFORMANCE. 


IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, 
INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN 
THE SOFTWARE OR ITS DOCUMENTATION, even if advised of the possibility of such 
damages. In particular, Apple shall have no liability for any programs or data stored in or 
used with Apple products, including the costs of recovering such programs or data. 


THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU 
OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, 
or employee is authorized to make any modification, extension, or addition to this warranty. 


Some states do not allow the exclusion or limitation of implied warranties or liability for 
incidental or consequential damages, so the above limitation or exclusion may not apply to 
you. This warranty gives you specific legal rights, and you may also have other rights which 
vary from state to state. 


HyperTalk.. 
Quick Reference Card 


the random of factor 
random (expression) 


the result 
result () 


the round of factor 
round (expression) 
the screenRect 


screenRect () 


the seconds 
seconds () 

the selectedText 
the selectedChunk 
the selectedLine 
the selectedField 
the shiftKey 
shiftKey () 

the sin of factor 
Sin (expression) 

the sound 

sound () 


the sqrt of factor 
sqrt (expression) 


the tan of factor 
tan (expression) 

the target 
target () 


the ticks 
ticks () 


the [modifier] time 
time () 

the tool 

tool () 

the trunc of factor 
txrunc (expression) 

the value of factor 
value (expression) 


the [long] version [of HyperCard] 
version () 


the version of stackDescriptor 


Gives a random integer from 1 to the value of factor 


Returns a text string if find or go is 
unsuccessful 


Rounds to nearest integer: an odd integer plus 0.5 
rounds up; an even integer, down 


The rectangle of the screen in which the menu bar 
is displayed: left, top, right, bottom coordinates 


Number of seconds between midnight January 1, 1904, 
and the current time in your Macintosh 


Returns the text currently selected 
Describes the location of the selected text 
Tells which line the selected text is in 
Tells which field the selected text is in 
Condition of the Shift key: up or down 


Sine—tradians 

Name of sound resource currently playing, or "done" 
if none is playing 

Square root of a positive number—a negative 
number gives the result NAN(001) meaning “not a 
number” 

Tangent—radians 

Identifies the original recipient of a message 

Number of ticks (%0 second) since the Macintosh was 
turned on or restarted 

Gives time as a text string: long, short, abbreviated 
Name of currently chosen tool 

The integer part of a number in function 

Gives the value of a string as an expression 


Returns the version number of HyperCard 


Tells version of HyperCard used to create, compact, 
change since compacted, and make latest changes, plus 
the date modified in seconds since January 1, 1904 


The information in this Quick Reference Card pertains to HyperCard version 1.2.2. 


Script editor command summary 


Key combination Action 

Command-A Select entire script 

Command-C Copy selection to Clipboard 

Command-F Find text (same as Find button) 

Command-G Find next occurrence of same text 

Command-H Find current selection 

Command-P Print selection or (if no selection) entire 
script (same as Print button) 

Command-period Close script without saving changes (same as 
Cancel button) 

Command-V Paste Clipboard contents at insertion point 

Command-X Cut selection to Clipboard 

Enter Close script and save changes (same as 
OK button) 

Option-Return Wrap line without return character (“soft” 


return—symbolized by > in scripts. Don’t 
use a “soft” return inside quotation marks.) 


Return Return character—indicates end of 
HyperTalk statement 
Tab Format script 


Shortcuts for seeing scripts 


Key combination Effect 
Command-Option Display buttons; click a button with 
keys down to edit its script 
Shift-Command-Option Display fields and buttons; click a field (or 
button) with keys down to edit its script 
Command-Option-C Edit script of current card 
Command-Option-B Edit script of current background 


Command-Option-S Edit script of current stack 


Commands 


In the statements listed below, square brackets [ ] enclose optional elements. (Don’t type the 
square brackets.) Words in italic are placeholders describing general elements, not specific names; 
you must replace them in an actual command. It doesn’t matter whether you use uppercase or 
lowercase letters in HyperTalk; names formed from two words are shown with an embedded 
capital letter (1 ikeThis) merely to make them more readable. The HyperTalk prepositions 

of and in are interchangeable. 


add expression to destination 

answer "question" [with "reply" [or "“reply2" [or "reply3"]]] 
arrowKey keyName 

ask [password] question [with defaultAnswer] 
beep number 

choose toolName tool 

click at location [with key[, key2[, key3]]] 
close file fileName 

close printing 

convert container to format [and format] 
controlKey asciiNumber 

delete chunk [of container] 

dial expression [with modem [modemCommands] | 
divide destination by expression 

doMenu menultem 

drag from start to finish [with key[, key2[, key3]]] 
edit script of object 

enterKey 

find [chars] expression [in field fieldDesignator] 
find [word] expression [in field fieldDesignator] 
find string expression [in field fieldDesignator] 
find whole expression [in field fieldDesignator] 
functionKey keyNumber 

get expression 

go [to] [stack] "stackName" 

go [to] bkgndDescriptor [of [stack] "stackName" ] 
go [to] cardDescriptor [of bkgndDescriptor} [of [stack] "stackName" | 
help 

hide menuBar 

hide windowName 

hide object 

hide picture 


the foundText 
the foundChunk 
the foundLine 
the foundField 


the length of factor 
length (expression) 

the ln of factor 

Ln (expression) 


the lnl of factor 
1lnl (expression) 


the log2 of factor 
log2 (expression) 


max (ist) 
min (ist) 


the mouse 
mouse () 


the mouseClick 
mouseClick () 


the mouseH 
mouseH () 


the mouseLoc 
mouseLoc() 


the mouseV 
mouseV () 


[the] number of objects 


[the] number of chunks in factor 


Returns characters found by the find command 
Returns a description of where the text is found 
Tells which line the found text is in 

Tells which field the found text is in 

Number of characters in a text string 


Natural logarithm—base-e 
1 plus the natural logarithm: 1n (1+factor) 
Base-2 logarithm 


Returns the highest number value of a list 
Returns the lowest number value of a list 
Condition of the mouse button: up or down 


Returns true if the mouse button is clicked 
Horizontal position of the pointer on the screen 
Horizontal and vertical coordinates of the pointer 
Vertical position of the pointer 

Number of buttons/fields on current card or bg 


Number of characters, words, lines, and so on in text 
string 


[the] number of cards of background Number of cards in specified background 


the numToChar of factor 
numToChar ( expression) 


offset (string1, string2) 


the optionKey 
optionkKey () 

the param of factor 
param (expression) 
the paramCount 
paramCount () 


the params 
params () 


Returns the character corresponding to an ASCII value 
Gives number of characters between the beginnings of 
two strings 

Condition of the Option key: up or down 

Returns the value of a parameter in a list 


The total number of parameters 


The entire list of parameters 


Functions 


In the statements listed below, square brackets [ ] enclose optional elements. (Don’t type the 
square brackets.) Words in italic are placeholders describing general elements, not specific names; 
you must replace them in an actual command. It doesn’t matter whether you use uppercase or 
lowercase letters in HyperTalk; names formed from two words are shown with an embedded 
capital letter (1 ikeThis) merely to make them more readable. The HyperTalk prepositions 
of and in are interchangeable. 


When using functions in HyperTalk statements you must either use the word the _ before the 
function name or add parentheses after it. Both forms are shown in the list that follows. Factor 


is a single value, such as the number 5 or a container holding a value; expression can be a single 
factor or a combination of several factors and operators that results in a value, such as (2+3) 
or (2+(field 1) ). Parameters in a list must be separated by commas. 


the abs of factor 
abs (expression) 


annuity (rate, periods) 


the atan of factor 
atan (expression) 


average (list) 


the charToNum of factor 


charToNum ( expression) 
the clickH 


the clickLoc 
clickLoc() 


the clickV 


the commandKey 
commandKey () 


compound (rate, periods) 


the cos of factor 
cos (expression) 


the [modifier] date 


the diskSpace 
diskSpace () 

the exp of factor 
exp (expression) 

the expl of factor 
exp (expression) 


the exp2 of factor 
exp2 (expression) 


Absolute value 


Calculates an annuity 
Arc tangent—radians 


Calculates an average 
Returns the ASCII value of a character 


Gives horizontal coordinate of where the user last clicked 


Gives horizontal and vertical coordinates of where the 
user last clicked 


Gives vertical coordinate of where the user last clicked 
Condition of the Command key: up or down 


Calculates compound interest 
Cosine—radians 


Current date set in the Macintosh: long or short 
Amount of free space on the current disk 


Mathematical exponential 
1 less than mathematical exponential: exp ()-1 


The value of 2 raised to the power of factor 


Lock «screen 

multiply destination by expression 

open [document with] application 

open file fileName 

open printing [with dialog] 

play "voice" [tempo tempoValue] ["notes"] 
play stop 

pop card [preposition destination] 

print card 

print expression cards 

print cardDescriptor 

print document with application 

push cardDescriptor 

put expression [preposition destination] 
read from file fileName until character 
read from file fileName for numberOfCharacters 


reset paint 


returnKkey 

select object 

select [preposition] expression of field 
select [preposition] expression of msg 
select [preposition] text of field 
select empty 

set [the] property [of object] to value 
show [all] cards 

show number cards 

show menuBar 

show windowName [at h,v] 

show object [at h,v] 

show picture 

sort [direction] [style] by expression 
subtract expression from destination 
tabKey 

type expression [with key[, key2(, key3]]] 
unlock screen [with effectName] 
visual [effect] effectName [speed] [to image] 
wait [for] number [seconds] 

wait until condition 

wait while condition 

write source to file fileName 
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Please contact your authorized Apple dealer when you have questions about your Apple products. Dealers are trained by 
Apple Computer and are given the resources to handle service and support for all Apple products. If you need the name of 
an authorized Apple dealer in your area, call toll-free: 800-538-9696. 


Would you like to tell Apple what you think about this product? After you have had an opportunity to use this product, we 
would like to hear from you. You can help us to improve our products by responding to the questionnaire below and marking 
the appropriate boxes on the card at the right with a #2 lead pencil. If you have more than one response to a question, mark 
all the boxes that apply. Please detach the card and mail it to Apple. Include additional pages of comments if you wish. 


. How long had you been using HyperCard before you used the HyperTalk Beginner's Guide? (1=less than one month, 


2=1-6 months, 3=6-12 months, 4=more than 1 year) 


. How much experience did you have with programming before you used the guide? (1=no experience, 2=some experience, 


3=extensive experience) 


. Had you tried scripting on your own before using the HyperTalk Beginner’s Guide? (1=no, 2=yes) 
. How would you rate the HyperTalk Beginner's Guide overall? (1=poor...6=excellent) 

. How easy was the guide to read and understand? (1=difficult...6=very easy) 

. How would you rate the organization of the guide? (1=poor...6=excellent) 


. How successful were you at completing the tasks in Chapters 1 through 5? (1=not successful with any task...6=completely 


successful with every task) 


. Did you try to build the example stacks in Chapter 6? (1=no, 2=yes) 

. How easy was it to write scripts in HyperTalk? (1=difficult...6=very easy) 

. To what degree do you expect to use scripting? (1=never...6=extensively) 

. How often did you use HyperCard before using the guide? (1=rarely...6=every day) 

. Do you think you'll use HyperCard more often now that you’ve used the HyperTalk Beginner’s Guide? (1=no, 2=yes) 
. Do you think the Quick Reference Card will be useful to you? (1=no, 2=yes) 

. What did you like best about the guide? 

. What did you like least about the guide? 

. If you experienced any problems with the guide, please describe them. (Page numbers would be useful.) 


. What suggestions do you have for improving the HyperTalk Beginner's Guide? 
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